@nhtio/adk 1.20260604.0 → 1.20260607.0

package/batteries/vector/duckdb.cjs

@@ -0,0 +1,218 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
+require("../../guards.cjs");
+const require_batteries_vector_filters = require("./filters.cjs");
+const require_batteries_vector_helpers = require("./helpers.cjs");
+const require_batteries_vector_exceptions = require("./exceptions.cjs");
+const require_batteries_vector_contract = require("./contract.cjs");
+const require_batteries_vector_validation = require("./validation.cjs");
+//#region src/batteries/vector/duckdb/index.ts
+/**
+* @module @nhtio/adk/batteries/vector/duckdb
+*
+* In-process DuckDB adapter (like sqlite_vec — no server). Uses the `vss` community
+* extension for vector distance functions over a `FLOAT[N]` column; metadata lives in a
+* `JSON` column filtered with DuckDB's `json_extract*` functions. Each collection is a
+* table; the document and id are plain columns.
+*
+* Driver: `@duckdb/node-api` (promise-based). Path defaults to `:memory:`.
+*/
+var getDuckDB = async () => {
+	try {
+		return (await import("@duckdb/node-api")).DuckDBInstance;
+	} catch {
+		throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DRIVER_UNAVAILABLE(["@duckdb/node-api"]);
+	}
+};
+var distanceFn = (metric) => metric === "euclidean" ? "array_distance" : metric === "dot" ? "array_negative_inner_product" : "array_cosine_distance";
+var ident = (name) => `"${name.replace(/"/g, "\"\"")}"`;
+var lit = (value) => `'${value.replace(/'/g, "''")}'`;
+var vectorLiteral = (vector) => `[${vector.map((n) => Number.isFinite(n) ? String(n) : "0").join(", ")}]::FLOAT[${vector.length}]`;
+var DuckDBVectorStore = class extends require_batteries_vector_contract.BaseVectorStore {
+	capabilities = {
+		transactions: true,
+		namedVectors: false,
+		rename: true,
+		rawSql: true,
+		builtInEncoding: false,
+		consistency: {
+			configurable: false,
+			default: "strong",
+			modes: ["strong"]
+		}
+	};
+	#instance = null;
+	#conn = null;
+	#dims = /* @__PURE__ */ new Map();
+	get #opts() {
+		return this.options;
+	}
+	static isAvailable() {
+		return typeof process !== "undefined";
+	}
+	isAvailable() {
+		return typeof process !== "undefined";
+	}
+	async connect() {
+		if (this.#conn) return;
+		const DuckDBInstance = await getDuckDB();
+		const path = this.#opts.connection?.path ?? ":memory:";
+		try {
+			this.#instance = await DuckDBInstance.create(path);
+			this.#conn = await this.#instance.connect();
+			await this.#conn.run("INSTALL vss;");
+			await this.#conn.run("LOAD vss;");
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_CONNECTION_FAILED([String(err)]);
+		}
+	}
+	async close() {
+		this.#conn = null;
+		this.#instance = null;
+	}
+	async #ensure() {
+		if (!this.#conn) await this.connect();
+		return this.#conn;
+	}
+	async #rows(sql) {
+		return (await (await this.#ensure()).runAndReadAll(sql)).getRows();
+	}
+	async createCollection(spec, ifNotExists) {
+		const conn = await this.#ensure();
+		this.#dims.set(spec.collection, spec.vector.dimensions);
+		const ine = ifNotExists ? "IF NOT EXISTS " : "";
+		try {
+			await conn.run(`CREATE TABLE ${ine}${ident(spec.collection)} (id VARCHAR PRIMARY KEY, vec FLOAT[${spec.vector.dimensions}], document VARCHAR, metadata JSON)`);
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["createCollection", String(err)]);
+		}
+	}
+	async dropCollection(collection, ifExists) {
+		const conn = await this.#ensure();
+		const ie = ifExists ? "IF EXISTS " : "";
+		try {
+			await conn.run(`DROP TABLE ${ie}${ident(collection)}`);
+			this.#dims.delete(collection);
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["dropCollection", String(err)]);
+		}
+	}
+	async hasCollection(collection) {
+		return (await this.#rows(`SELECT 1 FROM information_schema.tables WHERE table_name = ${lit(collection)}`)).length > 0;
+	}
+	async renameCollection(from, to) {
+		const conn = await this.#ensure();
+		try {
+			await conn.run(`ALTER TABLE ${ident(from)} RENAME TO ${ident(to)}`);
+			const d = this.#dims.get(from);
+			if (d !== void 0) {
+				this.#dims.set(to, d);
+				this.#dims.delete(from);
+			}
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UNSUPPORTED_OPERATION(["renameCollection", String(err)]);
+		}
+	}
+	async executeUpsert(plan) {
+		if (plan.records.length === 0) return;
+		require_batteries_vector_validation.validateRecords(plan.records);
+		const conn = await this.#ensure();
+		const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection);
+		try {
+			for (const r of plan.records) {
+				let vector = r.vector;
+				if (!vector && r.document) {
+					const [v] = await this.encode([r.document], "document");
+					vector = v;
+				}
+				if (!vector) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED(["Record missing vector and document"]);
+				if (expected !== void 0 && vector.length !== expected) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length]);
+				const meta = r.metadata ? JSON.stringify(r.metadata) : "{}";
+				const doc = r.document === void 0 ? "NULL" : lit(r.document);
+				await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id = ${lit(r.id)}`);
+				await conn.run(`INSERT INTO ${ident(plan.collection)} (id, vec, document, metadata) VALUES (${lit(r.id)}, ${vectorLiteral(vector)}, ${doc}, ${lit(meta)}::JSON)`);
+			}
+		} catch (err) {
+			if (require_tool_registry.isInstanceOf(err, "E_VECTOR_STORE_DIMENSION_MISMATCH", require_batteries_vector_exceptions.E_VECTOR_STORE_DIMENSION_MISMATCH) || require_tool_registry.isInstanceOf(err, "E_VECTOR_STORE_UPSERT_FAILED", require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED)) throw err;
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED([String(err)]);
+		}
+	}
+	async executeSearch(plan) {
+		const metric = this.#opts.metric ?? "cosine";
+		let queryVector;
+		if (plan.near) {
+			if ("vector" in plan.near) queryVector = plan.near.vector;
+			else if ("serverText" in plan.near) {
+				const [v] = await this.encode([plan.near.serverText], "query");
+				queryVector = v;
+			} else if ("id" in plan.near) {
+				const rows = await this.#rows(`SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)}`);
+				if (rows.length === 0) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_SEARCH_FAILED(["Referenced id not found: " + plan.near.id]);
+				queryVector = this.#unwrapVector(rows[0][0]);
+			}
+		}
+		const offset = plan.offset ?? 0;
+		try {
+			if (queryVector) {
+				const distExpr = `${distanceFn(metric)}(vec, ${vectorLiteral(queryVector)})`;
+				const rows = await this.#rows(`SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`);
+				const filtered = plan.filter ? rows.filter((row) => require_batteries_vector_filters.evaluateFilter(plan.filter, this.#parseMeta(row[3]))) : rows;
+				filtered.sort((a, b) => Number(a[4]) - Number(b[4]));
+				return filtered.slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, true));
+			} else {
+				const rows = await this.#rows(`SELECT id, vec, document, metadata, NULL AS __dist FROM ${ident(plan.collection)}`);
+				return (plan.filter ? rows.filter((row) => require_batteries_vector_filters.evaluateFilter(plan.filter, this.#parseMeta(row[3]))) : rows).slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, false));
+			}
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_SEARCH_FAILED([String(err)]);
+		}
+	}
+	#unwrapVector(val) {
+		if (val && typeof val === "object" && Array.isArray(val.items)) return val.items;
+		if (Array.isArray(val)) return val;
+		return [];
+	}
+	#parseMeta(val) {
+		if (val === null || val === void 0) return {};
+		if (typeof val === "string") try {
+			return JSON.parse(val);
+		} catch {
+			return {};
+		}
+		if (typeof val === "object") return val;
+		return {};
+	}
+	#project(row, plan, metric, isKnn) {
+		const [id, vec, document, metadata, dist] = row;
+		const proj = plan.projection;
+		const out = {};
+		if (proj.id) out.id = id;
+		if (proj.vector) out.vector = this.#unwrapVector(vec);
+		if (proj.document) out.document = document ?? void 0;
+		if (proj.metadata) out.metadata = this.#parseMeta(metadata);
+		if (isKnn && dist !== null && dist !== void 0) out.score = require_batteries_vector_helpers.normalizeScore(Number(dist), metric, "distance");
+		return out;
+	}
+	async executeDelete(plan) {
+		const conn = await this.#ensure();
+		try {
+			if (plan.ids && plan.ids.length > 0) {
+				const list = plan.ids.map((id) => lit(id)).join(", ");
+				await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`);
+			} else if (plan.filter) {
+				const targets = (await this.#rows(`SELECT id, metadata FROM ${ident(plan.collection)}`)).filter((row) => require_batteries_vector_filters.evaluateFilter(plan.filter, this.#parseMeta(row[1]))).map((row) => row[0]);
+				if (targets.length > 0) {
+					const list = targets.map((id) => lit(id)).join(", ");
+					await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`);
+				}
+			} else await conn.run(`DELETE FROM ${ident(plan.collection)}`);
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DELETE_FAILED([String(err)]);
+		}
+	}
+};
+//#endregion
+exports.DuckDBVectorStore = DuckDBVectorStore;
+
+//# sourceMappingURL=duckdb.cjs.map

package/batteries/vector/duckdb.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb.cjs","names":["#opts","#conn","#instance","#ensure","#rows","#dims","#unwrapVector","#parseMeta","#project"],"sources":["../../../src/batteries/vector/duckdb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/duckdb\n *\n * In-process DuckDB adapter (like sqlite_vec — no server). Uses the `vss` community\n * extension for vector distance functions over a `FLOAT[N]` column; metadata lives in a\n * `JSON` column filtered with DuckDB's `json_extract*` functions. Each collection is a\n * table; the document and id are plain columns.\n *\n * Driver: `@duckdb/node-api` (promise-based). Path defaults to `:memory:`.\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface DuckDBVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { path?: string }\n}\n\nconst getDuckDB = async () => {\n  try {\n    const mod = await import('@duckdb/node-api')\n    return mod.DuckDBInstance\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@duckdb/node-api'])\n  }\n}\n\n// DuckDB vss distance function per metric (all return a distance — lower is closer).\nconst distanceFn = (metric: DistanceMetric): string =>\n  metric === 'euclidean'\n    ? 'array_distance'\n    : metric === 'dot'\n      ? 'array_negative_inner_product'\n      : 'array_cosine_distance'\n\n// A double-quoted SQL identifier (table/column), escaping embedded quotes.\nconst ident = (name: string): string => `\"${name.replace(/\"/g, '\"\"')}\"`\n\n// A single-quoted SQL string literal, escaping embedded quotes.\nconst lit = (value: string): string => `'${value.replace(/'/g, \"''\")}'`\n\n// Render a number[] as a DuckDB FLOAT[N] array literal: [1.0, 2.0, ...]::FLOAT[N].\nconst vectorLiteral = (vector: number[]): string =>\n  `[${vector.map((n) => (Number.isFinite(n) ? String(n) : '0')).join(', ')}]::FLOAT[${vector.length}]`\n\nexport class DuckDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: true,\n    namedVectors: false,\n    rename: true,\n    rawSql: true,\n    builtInEncoding: false,\n    // In-process and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #instance: any | null = null\n  #conn: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): DuckDBVectorStoreOptions {\n    return this.options as DuckDBVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#conn) return\n    const DuckDBInstance = await getDuckDB()\n    const path = this.#opts.connection?.path ?? ':memory:'\n    try {\n      this.#instance = await DuckDBInstance.create(path)\n      this.#conn = await this.#instance.connect()\n      // vss provides the array_*_distance vector functions.\n      await this.#conn.run('INSTALL vss;')\n      await this.#conn.run('LOAD vss;')\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    // @duckdb/node-api connections are GC-managed; drop references.\n    this.#conn = null\n    this.#instance = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#conn) await this.connect()\n    return this.#conn!\n  }\n\n  async #rows(sql: string): Promise<any[][]> {\n    const conn = await this.#ensure()\n    const reader = await conn.runAndReadAll(sql)\n    return reader.getRows()\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const conn = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await conn.run(\n        `CREATE TABLE ${ine}${ident(spec.collection)} (` +\n          `id VARCHAR PRIMARY KEY, ` +\n          `vec FLOAT[${spec.vector.dimensions}], ` +\n          `document VARCHAR, ` +\n          `metadata JSON)`\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const conn = await this.#ensure()\n    const ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await conn.run(`DROP TABLE ${ie}${ident(collection)}`)\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const rows = await this.#rows(\n      `SELECT 1 FROM information_schema.tables WHERE table_name = ${lit(collection)}`\n    )\n    return rows.length > 0\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    const conn = await this.#ensure()\n    try {\n      await conn.run(`ALTER TABLE ${ident(from)} RENAME TO ${ident(to)}`)\n      const d = this.#dims.get(from)\n      if (d !== undefined) {\n        this.#dims.set(to, d)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const conn = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        const meta = r.metadata ? JSON.stringify(r.metadata) : '{}'\n        const doc = r.document === undefined ? 'NULL' : lit(r.document)\n        // DuckDB upsert: delete-then-insert keeps it simple and dialect-portable.\n        await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id = ${lit(r.id)}`)\n        await conn.run(\n          `INSERT INTO ${ident(plan.collection)} (id, vec, document, metadata) VALUES (` +\n            `${lit(r.id)}, ${vectorLiteral(vector)}, ${doc}, ${lit(meta)}::JSON)`\n        )\n      }\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await this.#rows(\n          `SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)}`\n        )\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = this.#unwrapVector(rows[0][0])\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Compute distance in DuckDB (vss), then apply the neutral filter with the JS\n        // reference evaluator before sorting + limiting — so similarity + filter semantics\n        // exactly match every other adapter. DuckDB scans are fast at the in-process scale.\n        const fn = distanceFn(metric)\n        const distExpr = `${fn}(vec, ${vectorLiteral(queryVector)})`\n        const rows = await this.#rows(\n          `SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row[3])))\n          : rows\n        filtered.sort((a, b) => Number(a[4]) - Number(b[4]))\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, true))\n      } else {\n        // Filter-scan: no similarity, just the neutral filter (JS evaluator) + limit.\n        const rows = await this.#rows(\n          `SELECT id, vec, document, metadata, NULL AS __dist FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row[3])))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #unwrapVector(val: unknown): number[] {\n    // DuckDB FLOAT[] comes back as { items: number[] } via node-api.\n    if (val && typeof val === 'object' && Array.isArray((val as any).items)) {\n      return (val as any).items as number[]\n    }\n    if (Array.isArray(val)) return val as number[]\n    return []\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (val === null || val === undefined) return {}\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any[], plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    // Row order: id, vec, document, metadata, __dist\n    const [id, vec, document, metadata, dist] = row\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = id as string\n    if (proj.vector) out.vector = this.#unwrapVector(vec)\n    if (proj.document) out.document = (document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(metadata)\n    if (isKnn && dist !== null && dist !== undefined) {\n      out.score = normalizeScore(Number(dist), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const conn = await this.#ensure()\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`)\n      } else if (plan.filter) {\n        // Resolve target ids in JS via the reference evaluator, then delete by id.\n        const rows = await this.#rows(`SELECT id, metadata FROM ${ident(plan.collection)}`)\n        const targets = rows\n          .filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row[1])))\n          .map((row) => row[0] as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`)\n        }\n      } else {\n        await conn.run(`DELETE FROM ${ident(plan.collection)}`)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/duckdb.mjs

@@ -0,0 +1,216 @@
+import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import "../../guards.mjs";
+import { evaluateFilter } from "./filters.mjs";
+import { normalizeScore } from "./helpers.mjs";
+import { E_VECTOR_STORE_COLLECTION_FAILED, E_VECTOR_STORE_CONNECTION_FAILED, E_VECTOR_STORE_DELETE_FAILED, E_VECTOR_STORE_DIMENSION_MISMATCH, E_VECTOR_STORE_DRIVER_UNAVAILABLE, E_VECTOR_STORE_SEARCH_FAILED, E_VECTOR_STORE_UNSUPPORTED_OPERATION, E_VECTOR_STORE_UPSERT_FAILED } from "./exceptions.mjs";
+import { BaseVectorStore } from "./contract.mjs";
+import { validateRecords } from "./validation.mjs";
+//#region src/batteries/vector/duckdb/index.ts
+/**
+* @module @nhtio/adk/batteries/vector/duckdb
+*
+* In-process DuckDB adapter (like sqlite_vec — no server). Uses the `vss` community
+* extension for vector distance functions over a `FLOAT[N]` column; metadata lives in a
+* `JSON` column filtered with DuckDB's `json_extract*` functions. Each collection is a
+* table; the document and id are plain columns.
+*
+* Driver: `@duckdb/node-api` (promise-based). Path defaults to `:memory:`.
+*/
+var getDuckDB = async () => {
+	try {
+		return (await import("@duckdb/node-api")).DuckDBInstance;
+	} catch {
+		throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(["@duckdb/node-api"]);
+	}
+};
+var distanceFn = (metric) => metric === "euclidean" ? "array_distance" : metric === "dot" ? "array_negative_inner_product" : "array_cosine_distance";
+var ident = (name) => `"${name.replace(/"/g, "\"\"")}"`;
+var lit = (value) => `'${value.replace(/'/g, "''")}'`;
+var vectorLiteral = (vector) => `[${vector.map((n) => Number.isFinite(n) ? String(n) : "0").join(", ")}]::FLOAT[${vector.length}]`;
+var DuckDBVectorStore = class extends BaseVectorStore {
+	capabilities = {
+		transactions: true,
+		namedVectors: false,
+		rename: true,
+		rawSql: true,
+		builtInEncoding: false,
+		consistency: {
+			configurable: false,
+			default: "strong",
+			modes: ["strong"]
+		}
+	};
+	#instance = null;
+	#conn = null;
+	#dims = /* @__PURE__ */ new Map();
+	get #opts() {
+		return this.options;
+	}
+	static isAvailable() {
+		return typeof process !== "undefined";
+	}
+	isAvailable() {
+		return typeof process !== "undefined";
+	}
+	async connect() {
+		if (this.#conn) return;
+		const DuckDBInstance = await getDuckDB();
+		const path = this.#opts.connection?.path ?? ":memory:";
+		try {
+			this.#instance = await DuckDBInstance.create(path);
+			this.#conn = await this.#instance.connect();
+			await this.#conn.run("INSTALL vss;");
+			await this.#conn.run("LOAD vss;");
+		} catch (err) {
+			throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)]);
+		}
+	}
+	async close() {
+		this.#conn = null;
+		this.#instance = null;
+	}
+	async #ensure() {
+		if (!this.#conn) await this.connect();
+		return this.#conn;
+	}
+	async #rows(sql) {
+		return (await (await this.#ensure()).runAndReadAll(sql)).getRows();
+	}
+	async createCollection(spec, ifNotExists) {
+		const conn = await this.#ensure();
+		this.#dims.set(spec.collection, spec.vector.dimensions);
+		const ine = ifNotExists ? "IF NOT EXISTS " : "";
+		try {
+			await conn.run(`CREATE TABLE ${ine}${ident(spec.collection)} (id VARCHAR PRIMARY KEY, vec FLOAT[${spec.vector.dimensions}], document VARCHAR, metadata JSON)`);
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["createCollection", String(err)]);
+		}
+	}
+	async dropCollection(collection, ifExists) {
+		const conn = await this.#ensure();
+		const ie = ifExists ? "IF EXISTS " : "";
+		try {
+			await conn.run(`DROP TABLE ${ie}${ident(collection)}`);
+			this.#dims.delete(collection);
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["dropCollection", String(err)]);
+		}
+	}
+	async hasCollection(collection) {
+		return (await this.#rows(`SELECT 1 FROM information_schema.tables WHERE table_name = ${lit(collection)}`)).length > 0;
+	}
+	async renameCollection(from, to) {
+		const conn = await this.#ensure();
+		try {
+			await conn.run(`ALTER TABLE ${ident(from)} RENAME TO ${ident(to)}`);
+			const d = this.#dims.get(from);
+			if (d !== void 0) {
+				this.#dims.set(to, d);
+				this.#dims.delete(from);
+			}
+		} catch (err) {
+			throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(["renameCollection", String(err)]);
+		}
+	}
+	async executeUpsert(plan) {
+		if (plan.records.length === 0) return;
+		validateRecords(plan.records);
+		const conn = await this.#ensure();
+		const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection);
+		try {
+			for (const r of plan.records) {
+				let vector = r.vector;
+				if (!vector && r.document) {
+					const [v] = await this.encode([r.document], "document");
+					vector = v;
+				}
+				if (!vector) throw new E_VECTOR_STORE_UPSERT_FAILED(["Record missing vector and document"]);
+				if (expected !== void 0 && vector.length !== expected) throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length]);
+				const meta = r.metadata ? JSON.stringify(r.metadata) : "{}";
+				const doc = r.document === void 0 ? "NULL" : lit(r.document);
+				await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id = ${lit(r.id)}`);
+				await conn.run(`INSERT INTO ${ident(plan.collection)} (id, vec, document, metadata) VALUES (${lit(r.id)}, ${vectorLiteral(vector)}, ${doc}, ${lit(meta)}::JSON)`);
+			}
+		} catch (err) {
+			if (isInstanceOf(err, "E_VECTOR_STORE_DIMENSION_MISMATCH", E_VECTOR_STORE_DIMENSION_MISMATCH) || isInstanceOf(err, "E_VECTOR_STORE_UPSERT_FAILED", E_VECTOR_STORE_UPSERT_FAILED)) throw err;
+			throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)]);
+		}
+	}
+	async executeSearch(plan) {
+		const metric = this.#opts.metric ?? "cosine";
+		let queryVector;
+		if (plan.near) {
+			if ("vector" in plan.near) queryVector = plan.near.vector;
+			else if ("serverText" in plan.near) {
+				const [v] = await this.encode([plan.near.serverText], "query");
+				queryVector = v;
+			} else if ("id" in plan.near) {
+				const rows = await this.#rows(`SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)}`);
+				if (rows.length === 0) throw new E_VECTOR_STORE_SEARCH_FAILED(["Referenced id not found: " + plan.near.id]);
+				queryVector = this.#unwrapVector(rows[0][0]);
+			}
+		}
+		const offset = plan.offset ?? 0;
+		try {
+			if (queryVector) {
+				const distExpr = `${distanceFn(metric)}(vec, ${vectorLiteral(queryVector)})`;
+				const rows = await this.#rows(`SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`);
+				const filtered = plan.filter ? rows.filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row[3]))) : rows;
+				filtered.sort((a, b) => Number(a[4]) - Number(b[4]));
+				return filtered.slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, true));
+			} else {
+				const rows = await this.#rows(`SELECT id, vec, document, metadata, NULL AS __dist FROM ${ident(plan.collection)}`);
+				return (plan.filter ? rows.filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row[3]))) : rows).slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, metric, false));
+			}
+		} catch (err) {
+			throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)]);
+		}
+	}
+	#unwrapVector(val) {
+		if (val && typeof val === "object" && Array.isArray(val.items)) return val.items;
+		if (Array.isArray(val)) return val;
+		return [];
+	}
+	#parseMeta(val) {
+		if (val === null || val === void 0) return {};
+		if (typeof val === "string") try {
+			return JSON.parse(val);
+		} catch {
+			return {};
+		}
+		if (typeof val === "object") return val;
+		return {};
+	}
+	#project(row, plan, metric, isKnn) {
+		const [id, vec, document, metadata, dist] = row;
+		const proj = plan.projection;
+		const out = {};
+		if (proj.id) out.id = id;
+		if (proj.vector) out.vector = this.#unwrapVector(vec);
+		if (proj.document) out.document = document ?? void 0;
+		if (proj.metadata) out.metadata = this.#parseMeta(metadata);
+		if (isKnn && dist !== null && dist !== void 0) out.score = normalizeScore(Number(dist), metric, "distance");
+		return out;
+	}
+	async executeDelete(plan) {
+		const conn = await this.#ensure();
+		try {
+			if (plan.ids && plan.ids.length > 0) {
+				const list = plan.ids.map((id) => lit(id)).join(", ");
+				await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`);
+			} else if (plan.filter) {
+				const targets = (await this.#rows(`SELECT id, metadata FROM ${ident(plan.collection)}`)).filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row[1]))).map((row) => row[0]);
+				if (targets.length > 0) {
+					const list = targets.map((id) => lit(id)).join(", ");
+					await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`);
+				}
+			} else await conn.run(`DELETE FROM ${ident(plan.collection)}`);
+		} catch (err) {
+			throw new E_VECTOR_STORE_DELETE_FAILED([String(err)]);
+		}
+	}
+};
+//#endregion
+export { DuckDBVectorStore };
+
+//# sourceMappingURL=duckdb.mjs.map

package/batteries/vector/duckdb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb.mjs","names":["#opts","#conn","#instance","#ensure","#rows","#dims","#unwrapVector","#parseMeta","#project"],"sources":["../../../src/batteries/vector/duckdb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/duckdb\n *\n * In-process DuckDB adapter (like sqlite_vec — no server). Uses the `vss` community\n * extension for vector distance functions over a `FLOAT[N]` column; metadata lives in a\n * `JSON` column filtered with DuckDB's `json_extract*` functions. Each collection is a\n * table; the document and id are plain columns.\n *\n * Driver: `@duckdb/node-api` (promise-based). Path defaults to `:memory:`.\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface DuckDBVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { path?: string }\n}\n\nconst getDuckDB = async () => {\n  try {\n    const mod = await import('@duckdb/node-api')\n    return mod.DuckDBInstance\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@duckdb/node-api'])\n  }\n}\n\n// DuckDB vss distance function per metric (all return a distance — lower is closer).\nconst distanceFn = (metric: DistanceMetric): string =>\n  metric === 'euclidean'\n    ? 'array_distance'\n    : metric === 'dot'\n      ? 'array_negative_inner_product'\n      : 'array_cosine_distance'\n\n// A double-quoted SQL identifier (table/column), escaping embedded quotes.\nconst ident = (name: string): string => `\"${name.replace(/\"/g, '\"\"')}\"`\n\n// A single-quoted SQL string literal, escaping embedded quotes.\nconst lit = (value: string): string => `'${value.replace(/'/g, \"''\")}'`\n\n// Render a number[] as a DuckDB FLOAT[N] array literal: [1.0, 2.0, ...]::FLOAT[N].\nconst vectorLiteral = (vector: number[]): string =>\n  `[${vector.map((n) => (Number.isFinite(n) ? String(n) : '0')).join(', ')}]::FLOAT[${vector.length}]`\n\nexport class DuckDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: true,\n    namedVectors: false,\n    rename: true,\n    rawSql: true,\n    builtInEncoding: false,\n    // In-process and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #instance: any | null = null\n  #conn: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): DuckDBVectorStoreOptions {\n    return this.options as DuckDBVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#conn) return\n    const DuckDBInstance = await getDuckDB()\n    const path = this.#opts.connection?.path ?? ':memory:'\n    try {\n      this.#instance = await DuckDBInstance.create(path)\n      this.#conn = await this.#instance.connect()\n      // vss provides the array_*_distance vector functions.\n      await this.#conn.run('INSTALL vss;')\n      await this.#conn.run('LOAD vss;')\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    // @duckdb/node-api connections are GC-managed; drop references.\n    this.#conn = null\n    this.#instance = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#conn) await this.connect()\n    return this.#conn!\n  }\n\n  async #rows(sql: string): Promise<any[][]> {\n    const conn = await this.#ensure()\n    const reader = await conn.runAndReadAll(sql)\n    return reader.getRows()\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const conn = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await conn.run(\n        `CREATE TABLE ${ine}${ident(spec.collection)} (` +\n          `id VARCHAR PRIMARY KEY, ` +\n          `vec FLOAT[${spec.vector.dimensions}], ` +\n          `document VARCHAR, ` +\n          `metadata JSON)`\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const conn = await this.#ensure()\n    const ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await conn.run(`DROP TABLE ${ie}${ident(collection)}`)\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const rows = await this.#rows(\n      `SELECT 1 FROM information_schema.tables WHERE table_name = ${lit(collection)}`\n    )\n    return rows.length > 0\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    const conn = await this.#ensure()\n    try {\n      await conn.run(`ALTER TABLE ${ident(from)} RENAME TO ${ident(to)}`)\n      const d = this.#dims.get(from)\n      if (d !== undefined) {\n        this.#dims.set(to, d)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const conn = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        const meta = r.metadata ? JSON.stringify(r.metadata) : '{}'\n        const doc = r.document === undefined ? 'NULL' : lit(r.document)\n        // DuckDB upsert: delete-then-insert keeps it simple and dialect-portable.\n        await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id = ${lit(r.id)}`)\n        await conn.run(\n          `INSERT INTO ${ident(plan.collection)} (id, vec, document, metadata) VALUES (` +\n            `${lit(r.id)}, ${vectorLiteral(vector)}, ${doc}, ${lit(meta)}::JSON)`\n        )\n      }\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await this.#rows(\n          `SELECT vec FROM ${ident(plan.collection)} WHERE id = ${lit(plan.near.id)}`\n        )\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = this.#unwrapVector(rows[0][0])\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Compute distance in DuckDB (vss), then apply the neutral filter with the JS\n        // reference evaluator before sorting + limiting — so similarity + filter semantics\n        // exactly match every other adapter. DuckDB scans are fast at the in-process scale.\n        const fn = distanceFn(metric)\n        const distExpr = `${fn}(vec, ${vectorLiteral(queryVector)})`\n        const rows = await this.#rows(\n          `SELECT id, vec, document, metadata, ${distExpr} AS __dist FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row[3])))\n          : rows\n        filtered.sort((a, b) => Number(a[4]) - Number(b[4]))\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, true))\n      } else {\n        // Filter-scan: no similarity, just the neutral filter (JS evaluator) + limit.\n        const rows = await this.#rows(\n          `SELECT id, vec, document, metadata, NULL AS __dist FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row[3])))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #unwrapVector(val: unknown): number[] {\n    // DuckDB FLOAT[] comes back as { items: number[] } via node-api.\n    if (val && typeof val === 'object' && Array.isArray((val as any).items)) {\n      return (val as any).items as number[]\n    }\n    if (Array.isArray(val)) return val as number[]\n    return []\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (val === null || val === undefined) return {}\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any[], plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    // Row order: id, vec, document, metadata, __dist\n    const [id, vec, document, metadata, dist] = row\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = id as string\n    if (proj.vector) out.vector = this.#unwrapVector(vec)\n    if (proj.document) out.document = (document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(metadata)\n    if (isKnn && dist !== null && dist !== undefined) {\n      out.score = normalizeScore(Number(dist), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const conn = await this.#ensure()\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`)\n      } else if (plan.filter) {\n        // Resolve target ids in JS via the reference evaluator, then delete by id.\n        const rows = await this.#rows(`SELECT id, metadata FROM ${ident(plan.collection)}`)\n        const targets = rows\n          .filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row[1])))\n          .map((row) => row[0] as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await conn.run(`DELETE FROM ${ident(plan.collection)} WHERE id IN (${list})`)\n        }\n      } else {\n        await conn.run(`DELETE FROM ${ident(plan.collection)}`)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/elasticsearch/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @module @nhtio/adk/batteries/vector/elasticsearch
+ *
+ * Elasticsearch 8 adapter — each collection is an index with a `dense_vector` field; KNN uses ES8's
+ * top-level `knn` search clause with an optional `filter`; the neutral filter tree compiles to bool/term/range
+ * over `metadata.*`. Distinct from the opensearch adapter (which speaks OpenSearch's `knn_vector`/`query.knn` dialect).
+ */
+import { BaseVectorStore } from "../contract";
+import type { VectorFilter } from "../filters";
+import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
+import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
+export interface ElasticsearchVectorStoreOptions extends BaseVectorStoreOptions {
+    connection?: {
+        node?: string;
+        auth?: {
+            username: string;
+            password: string;
+        } | {
+            apiKey: string;
+        };
+        client?: unknown;
+    };
+}
+/**
+ * Compile the neutral filter tree to an Elasticsearch bool-query clause over `metadata.*`.
+ * String values use the `.keyword` sub-field for exact match; numbers use range/term.
+ */
+export declare const translateElasticsearchFilter: (filter?: VectorFilter) => Record<string, unknown> | undefined;
+export declare class ElasticsearchVectorStore extends BaseVectorStore {
+    #private;
+    readonly capabilities: VectorStoreCapabilities;
+    static isAvailable(): boolean;
+    isAvailable(): boolean;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void>;
+    dropCollection(collection: string, ifExists: boolean): Promise<void>;
+    hasCollection(collection: string): Promise<boolean>;
+    renameCollection(_from: string, _to: string): Promise<void>;
+    executeUpsert(plan: UpsertPlan): Promise<void>;
+    executeSearch(plan: SearchPlan): Promise<VectorMatch[]>;
+    executeDelete(plan: DeletePlan): Promise<void>;
+}