@nhtio/adk 1.20260604.0 → 1.20260607.0

package/batteries/vector/milvus.mjs

@@ -0,0 +1,354 @@
+import { isFilterCondition, isFilterGroup, isRawFilter } 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_FILTER_OPERATOR, E_VECTOR_STORE_UPSERT_FAILED } from "./exceptions.mjs";
+import { BaseVectorStore } from "./contract.mjs";
+import { validateRecords } from "./validation.mjs";
+//#region src/batteries/vector/milvus/index.ts
+/**
+* @module @nhtio/adk/batteries/vector/milvus
+*/
+var getMilvusClient = async () => {
+	try {
+		return (await import("@zilliz/milvus2-sdk-node")).MilvusClient;
+	} catch {
+		throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(["@zilliz/milvus2-sdk-node"]);
+	}
+};
+var getDataType = async () => {
+	try {
+		return (await import("@zilliz/milvus2-sdk-node")).DataType;
+	} catch {
+		throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(["@zilliz/milvus2-sdk-node"]);
+	}
+};
+var mapMetricToMilvus = (metric) => {
+	if (metric === "cosine") return "COSINE";
+	if (metric === "dot") return "IP";
+	if (metric === "euclidean") return "L2";
+	return "COSINE";
+};
+var MilvusVectorStore = class extends BaseVectorStore {
+	capabilities = {
+		transactions: false,
+		namedVectors: false,
+		rename: true,
+		rawSql: false,
+		builtInEncoding: false,
+		consistency: {
+			configurable: false,
+			default: "strong",
+			modes: ["strong"]
+		}
+	};
+	#client = 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.#client) return;
+		const MilvusClient = await getMilvusClient();
+		const c = this.#opts.connection || {};
+		let address = c.address;
+		if (!address && c.url) try {
+			const url = new URL(c.url);
+			address = `${url.hostname}:${url.port || (url.protocol === "https:" ? "443" : "19530")}`;
+		} catch {
+			throw new E_VECTOR_STORE_CONNECTION_FAILED(["Invalid connection URL"]);
+		}
+		if (!address) address = "localhost:19530";
+		try {
+			this.#client = new MilvusClient({
+				address,
+				token: c.token,
+				username: c.username,
+				password: c.password,
+				ssl: c.ssl
+			});
+		} catch (err) {
+			throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)]);
+		}
+	}
+	async close() {
+		if (this.#client) {
+			await this.#client.closeConnection?.();
+			this.#client = null;
+		}
+	}
+	async createCollection(spec, ifNotExists) {
+		const client = this.#client || (await this.connect(), this.#client);
+		const collectionName = spec.collection;
+		const metric = spec.vector.metric ?? "cosine";
+		const dim = spec.vector.dimensions;
+		if (ifNotExists && await this.hasCollection(collectionName)) return;
+		try {
+			const has = await client.hasCollection({ collection_name: collectionName });
+			if (has.value && !ifNotExists) throw new E_VECTOR_STORE_COLLECTION_FAILED(["create", "collection exists"]);
+			if (has.value && ifNotExists) return;
+			const DataType = await getDataType();
+			await client.createCollection({
+				collection_name: collectionName,
+				fields: [
+					{
+						name: "id",
+						data_type: DataType.VarChar,
+						is_primary_key: true,
+						max_length: 512
+					},
+					{
+						name: "vector",
+						data_type: DataType.FloatVector,
+						dim
+					},
+					{
+						name: "document",
+						data_type: DataType.VarChar,
+						max_length: 65535
+					},
+					{
+						name: "metadata",
+						data_type: DataType.JSON
+					}
+				]
+			});
+			const indexType = "AUTOINDEX";
+			const metricType = mapMetricToMilvus(metric);
+			await client.createIndex({
+				collection_name: collectionName,
+				field_name: "vector",
+				index_type: indexType,
+				metric_type: metricType
+			});
+			await client.loadCollectionSync({ collection_name: collectionName });
+			this.#dims.set(collectionName, dim);
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["createCollection", String(err)]);
+		}
+	}
+	async dropCollection(collection, ifExists) {
+		const client = this.#client || (await this.connect(), this.#client);
+		if (ifExists && !await this.hasCollection(collection)) return;
+		try {
+			if (!(await client.hasCollection({ collection_name: collection })).value && !ifExists) throw new E_VECTOR_STORE_COLLECTION_FAILED(["drop", "collection does not exist"]);
+			await client.dropCollection({ collection_name: collection });
+			this.#dims.delete(collection);
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["dropCollection", String(err)]);
+		}
+	}
+	async hasCollection(collection) {
+		const client = this.#client || (await this.connect(), this.#client);
+		try {
+			return !!(await client.hasCollection({ collection_name: collection })).value;
+		} catch {
+			return false;
+		}
+	}
+	async renameCollection(from, to) {
+		const client = this.#client || (await this.connect(), this.#client);
+		try {
+			await client.renameCollection({
+				old_collection_name: from,
+				new_collection_name: to
+			});
+			if (this.#dims.has(from)) {
+				this.#dims.set(to, this.#dims.get(from));
+				this.#dims.delete(from);
+			}
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["renameCollection", String(err)]);
+		}
+	}
+	async executeUpsert(plan) {
+		if (plan.records.length === 0) return;
+		validateRecords(plan.records);
+		const client = this.#client || (await this.connect(), this.#client);
+		const collectionName = plan.collection;
+		const dim = this.#dims.get(collectionName);
+		const rows = [];
+		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 (dim !== void 0 && vector.length !== dim) throw new E_VECTOR_STORE_DIMENSION_MISMATCH([dim, vector.length]);
+			rows.push({
+				id: r.id,
+				vector,
+				document: r.document ?? "",
+				metadata: r.metadata ?? {}
+			});
+		}
+		try {
+			await client.upsert({
+				collection_name: collectionName,
+				data: rows
+			});
+			await client.flushSync({ collection_names: [collectionName] });
+		} catch (err) {
+			throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)]);
+		}
+	}
+	async executeSearch(plan) {
+		const client = this.#client || (await this.connect(), this.#client);
+		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 res = await client.query({
+					collection_name: plan.collection,
+					filter: `id == "${plan.near.id}"`,
+					output_fields: ["vector"]
+				});
+				if (res.data.length === 0) throw new E_VECTOR_STORE_SEARCH_FAILED(["Referenced id not found: " + plan.near.id]);
+				queryVector = res.data[0].vector;
+			}
+		}
+		const outputFields = [
+			"id",
+			"document",
+			"metadata"
+		];
+		if (plan.projection.vector) outputFields.push("vector");
+		const milvusFilter = translateMilvusFilter(plan.filter);
+		let results;
+		if (queryVector) results = await client.search({
+			collection_name: plan.collection,
+			data: [queryVector],
+			limit: plan.topK,
+			offset: plan.offset,
+			filter: milvusFilter,
+			output_fields: outputFields,
+			consistency_level: "Strong"
+		});
+		else results = await client.query({
+			collection_name: plan.collection,
+			filter: milvusFilter || "",
+			limit: plan.topK,
+			offset: plan.offset,
+			output_fields: outputFields,
+			consistency_level: "Strong"
+		});
+		const hitList = results.results || results.data || [];
+		const proj = plan.projection;
+		return hitList.map((hit) => this.projectHit(hit, proj, metric));
+	}
+	async executeDelete(plan) {
+		const client = this.#client || (await this.connect(), this.#client);
+		try {
+			const collectionName = plan.collection;
+			if (plan.ids) {
+				const filter = `id in [${plan.ids.map((i) => JSON.stringify(i)).join(",")}]`;
+				await client.delete({
+					collection_name: collectionName,
+					filter
+				});
+			} else if (plan.filter) {
+				const filter = translateMilvusFilter(plan.filter);
+				await client.delete({
+					collection_name: collectionName,
+					filter
+				});
+			} else await client.delete({
+				collection_name: collectionName,
+				filter: "id != \"\""
+			});
+		} catch (err) {
+			throw new E_VECTOR_STORE_DELETE_FAILED([String(err)]);
+		}
+	}
+	projectHit(hit, projection, metric) {
+		const out = {};
+		if (projection.id) out.id = hit.id;
+		if (projection.vector && "vector" in hit) out.vector = hit.vector;
+		if (projection.document) out.document = hit.document;
+		if (projection.metadata) out.metadata = hit.metadata;
+		if ("score" in hit && hit.score !== void 0) {
+			const kind = metric === "euclidean" ? "distance" : "similarity";
+			out.score = normalizeScore(hit.score, metric, kind);
+		}
+		return out;
+	}
+	translateMilvusFilter(filter) {
+		return translateMilvusFilter(filter);
+	}
+};
+var translateMilvusFilter = (filter) => {
+	if (!filter) return "";
+	if (isRawFilter(filter)) {
+		if (filter.$dialect === "milvus" && typeof filter.$raw === "string") return filter.$raw;
+		throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(["milvus", String(filter.$dialect)]);
+	}
+	if (isFilterCondition(filter)) {
+		const { field, op, value } = filter;
+		const jsonField = `metadata["${field}"]`;
+		if (value === void 0) {
+			if (op === "exists") return `exists ${jsonField}`;
+			throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(["milvus", op]);
+		}
+		const toJsonValue = (v) => {
+			if (typeof v === "string") return JSON.stringify(v);
+			if (typeof v === "number" || typeof v === "boolean") return String(v);
+			if (Array.isArray(v)) return `[${v.map(toJsonValue).join(",")}]`;
+			return JSON.stringify(v);
+		};
+		if (op === "eq") return `${jsonField} == ${toJsonValue(value)}`;
+		if (op === "ne") return `${jsonField} != ${toJsonValue(value)}`;
+		if (op === "gt") return `${jsonField} > ${toJsonValue(value)}`;
+		if (op === "gte") return `${jsonField} >= ${toJsonValue(value)}`;
+		if (op === "lt") return `${jsonField} < ${toJsonValue(value)}`;
+		if (op === "lte") return `${jsonField} <= ${toJsonValue(value)}`;
+		if (op === "in") {
+			if (!Array.isArray(value)) return "";
+			return `${jsonField} in [${value.map(toJsonValue).join(",")}]`;
+		}
+		if (op === "nin") {
+			if (!Array.isArray(value)) return "";
+			return `${jsonField} not in [${value.map(toJsonValue).join(",")}]`;
+		}
+		if (op === "exists") return `exists ${jsonField}`;
+		if (op === "contains") return `json_contains(${jsonField}, ${toJsonValue(value)})`;
+		throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(["milvus", op]);
+	}
+	if (isFilterGroup(filter)) {
+		const { and, or, not } = filter;
+		const parts = [];
+		if (and) {
+			const children = and.map((f) => translateMilvusFilter(f)).filter((c) => c !== "");
+			if (children.length === 0) return "";
+			if (children.length === 1) return children[0];
+			parts.push(`(${children.join(" && ")})`);
+		}
+		if (or) {
+			const children = or.map((f) => translateMilvusFilter(f)).filter((c) => c !== "");
+			if (children.length === 0) return "";
+			if (children.length === 1) return children[0];
+			parts.push(`(${children.join(" || ")})`);
+		}
+		if (not) {
+			const child = translateMilvusFilter(not);
+			if (child === "") return "";
+			parts.push(`!(${child})`);
+		}
+		if (parts.length === 0) return "";
+		if (parts.length === 1) return parts[0];
+		return parts.join(" && ");
+	}
+	return "";
+};
+//#endregion
+export { MilvusVectorStore, translateMilvusFilter };
+
+//# sourceMappingURL=milvus.mjs.map

package/batteries/vector/milvus.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"milvus.mjs","names":["#opts","#client","#dims"],"sources":["../../../src/batteries/vector/milvus/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/milvus\n */\n\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isFilterCondition, isRawFilter, isFilterGroup } from '../filters'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\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_FILTER_OPERATOR,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n} from '../exceptions'\nimport type { VectorFilter } from '../filters'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from '../types'\n\nexport interface MilvusVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: {\n    address?: string\n    url?: string\n    token?: string\n    username?: string\n    password?: string\n    ssl?: boolean\n  }\n}\n\nconst getMilvusClient = async () => {\n  try {\n    const mod = await import('@zilliz/milvus2-sdk-node')\n    return mod.MilvusClient\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@zilliz/milvus2-sdk-node'])\n  }\n}\n\nconst getDataType = async () => {\n  try {\n    const mod = await import('@zilliz/milvus2-sdk-node')\n    return mod.DataType\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@zilliz/milvus2-sdk-node'])\n  }\n}\n\nconst mapMetricToMilvus = (metric: string): string => {\n  if (metric === 'cosine') return 'COSINE'\n  if (metric === 'dot') return 'IP'\n  if (metric === 'euclidean') return 'L2'\n  return 'COSINE'\n}\n\nexport class MilvusVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Strongly consistent (search/query use consistency_level 'Strong'); the option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n  get #opts() {\n    return this.options as MilvusVectorStoreOptions\n  }\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const MilvusClient = await getMilvusClient()\n    const c = this.#opts.connection || {}\n    let address = c.address\n    if (!address && c.url) {\n      try {\n        const url = new URL(c.url)\n        const host = url.hostname\n        const port = url.port || (url.protocol === 'https:' ? '443' : '19530')\n        address = `${host}:${port}`\n      } catch {\n        throw new E_VECTOR_STORE_CONNECTION_FAILED(['Invalid connection URL'])\n      }\n    }\n    if (!address) {\n      address = 'localhost:19530'\n    }\n    try {\n      this.#client = new MilvusClient({\n        address,\n        token: c.token,\n        username: c.username,\n        password: c.password,\n        ssl: c.ssl,\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n  async close(): Promise<void> {\n    if (this.#client) {\n      await this.#client.closeConnection?.()\n      this.#client = null\n    }\n  }\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = this.#client || (await this.connect(), this.#client!)\n    const collectionName = spec.collection\n    const metric = spec.vector.metric ?? 'cosine'\n    const dim = spec.vector.dimensions\n    if (ifNotExists && (await this.hasCollection(collectionName))) return\n    try {\n      const has = await client.hasCollection({ collection_name: collectionName })\n      if (has.value && !ifNotExists) {\n        throw new E_VECTOR_STORE_COLLECTION_FAILED(['create', 'collection exists'])\n      }\n      if (has.value && ifNotExists) return\n      const DataType = await getDataType()\n      await client.createCollection({\n        collection_name: collectionName,\n        fields: [\n          { name: 'id', data_type: DataType.VarChar, is_primary_key: true, max_length: 512 },\n          { name: 'vector', data_type: DataType.FloatVector, dim },\n          { name: 'document', data_type: DataType.VarChar, max_length: 65535 },\n          { name: 'metadata', data_type: DataType.JSON },\n        ],\n      })\n      const indexType = 'AUTOINDEX'\n      const metricType = mapMetricToMilvus(metric)\n      await client.createIndex({\n        collection_name: collectionName,\n        field_name: 'vector',\n        index_type: indexType,\n        metric_type: metricType,\n      })\n      await client.loadCollectionSync({ collection_name: collectionName })\n      this.#dims.set(collectionName, dim)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = this.#client || (await this.connect(), this.#client!)\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      const has = await client.hasCollection({ collection_name: collection })\n      if (!has.value && !ifExists) {\n        throw new E_VECTOR_STORE_COLLECTION_FAILED(['drop', 'collection does not exist'])\n      }\n      await client.dropCollection({ collection_name: collection })\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n  async hasCollection(collection: string): Promise<boolean> {\n    const client = this.#client || (await this.connect(), this.#client!)\n    try {\n      const r = await client.hasCollection({ collection_name: collection })\n      return !!r.value\n    } catch {\n      return false\n    }\n  }\n  async renameCollection(from: string, to: string): Promise<void> {\n    const client = this.#client || (await this.connect(), this.#client!)\n    try {\n      await client.renameCollection({ old_collection_name: from, new_collection_name: to })\n      if (this.#dims.has(from)) {\n        this.#dims.set(to, this.#dims.get(from)!)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['renameCollection', String(err)])\n    }\n  }\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = this.#client || (await this.connect(), this.#client!)\n    const collectionName = plan.collection\n    const dim = this.#dims.get(collectionName)\n    const rows: any[] = []\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 (dim !== undefined && vector.length !== dim) {\n        throw new E_VECTOR_STORE_DIMENSION_MISMATCH([dim, vector.length])\n      }\n      rows.push({\n        id: r.id,\n        vector,\n        document: r.document ?? '',\n        metadata: r.metadata ?? {},\n      })\n    }\n    try {\n      await client.upsert({ collection_name: collectionName, data: rows })\n      await client.flushSync({ collection_names: [collectionName] })\n    } catch (err) {\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const client = this.#client || (await this.connect(), this.#client!)\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 res = await client.query({\n          collection_name: plan.collection,\n          filter: `id == \"${plan.near.id}\"`,\n          output_fields: ['vector'],\n        })\n        if (res.data.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = res.data[0].vector as number[]\n      }\n    }\n    const outputFields = ['id', 'document', 'metadata']\n    if (plan.projection.vector) {\n      outputFields.push('vector')\n    }\n    const milvusFilter = translateMilvusFilter(plan.filter)\n    let results: any\n    if (queryVector) {\n      results = await client.search({\n        collection_name: plan.collection,\n        data: [queryVector],\n        limit: plan.topK,\n        offset: plan.offset,\n        filter: milvusFilter,\n        output_fields: outputFields,\n        consistency_level: 'Strong',\n      })\n    } else {\n      results = await client.query({\n        collection_name: plan.collection,\n        filter: milvusFilter || '',\n        limit: plan.topK,\n        offset: plan.offset,\n        output_fields: outputFields,\n        consistency_level: 'Strong',\n      })\n    }\n    const hitList = results.results || results.data || []\n    const proj = plan.projection\n    return hitList.map((hit: any) => this.projectHit(hit, proj, metric))\n  }\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = this.#client || (await this.connect(), this.#client!)\n    try {\n      const collectionName = plan.collection\n      if (plan.ids) {\n        const filter = `id in [${plan.ids.map((i) => JSON.stringify(i)).join(',')}]`\n        await client.delete({ collection_name: collectionName, filter })\n      } else if (plan.filter) {\n        const filter = translateMilvusFilter(plan.filter)\n        await client.delete({ collection_name: collectionName, filter })\n      } else {\n        await client.delete({ collection_name: collectionName, filter: 'id != \"\"' })\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n  projectHit(hit: any, projection: any, metric: string): VectorMatch {\n    const out: VectorMatch = {}\n    if (projection.id) {\n      out.id = hit.id\n    }\n    if (projection.vector && 'vector' in hit) {\n      out.vector = hit.vector\n    }\n    if (projection.document) {\n      out.document = hit.document\n    }\n    if (projection.metadata) {\n      out.metadata = hit.metadata\n    }\n    if ('score' in hit && hit.score !== undefined) {\n      const kind = metric === 'euclidean' ? 'distance' : 'similarity'\n      out.score = normalizeScore(hit.score as number, metric as any, kind)\n    }\n    return out\n  }\n  translateMilvusFilter(filter?: VectorFilter): string {\n    return translateMilvusFilter(filter)\n  }\n}\n\nexport const translateMilvusFilter = (filter?: VectorFilter): string => {\n  if (!filter) return ''\n  if (isRawFilter(filter)) {\n    if (filter.$dialect === 'milvus' && typeof filter.$raw === 'string') {\n      return filter.$raw\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['milvus', String(filter.$dialect)])\n  }\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    const jsonField = `metadata[\"${field}\"]`\n    if (value === undefined) {\n      if (op === 'exists') {\n        return `exists ${jsonField}`\n      }\n      throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['milvus', op])\n    }\n    const toJsonValue = (v: unknown): string => {\n      if (typeof v === 'string') return JSON.stringify(v)\n      if (typeof v === 'number' || typeof v === 'boolean') return String(v)\n      if (Array.isArray(v)) {\n        return `[${v.map(toJsonValue).join(',')}]`\n      }\n      return JSON.stringify(v)\n    }\n    if (op === 'eq') return `${jsonField} == ${toJsonValue(value)}`\n    if (op === 'ne') return `${jsonField} != ${toJsonValue(value)}`\n    if (op === 'gt') return `${jsonField} > ${toJsonValue(value)}`\n    if (op === 'gte') return `${jsonField} >= ${toJsonValue(value)}`\n    if (op === 'lt') return `${jsonField} < ${toJsonValue(value)}`\n    if (op === 'lte') return `${jsonField} <= ${toJsonValue(value)}`\n    if (op === 'in') {\n      if (!Array.isArray(value)) return ''\n      return `${jsonField} in [${value.map(toJsonValue).join(',')}]`\n    }\n    if (op === 'nin') {\n      if (!Array.isArray(value)) return ''\n      return `${jsonField} not in [${value.map(toJsonValue).join(',')}]`\n    }\n    if (op === 'exists') {\n      return `exists ${jsonField}`\n    }\n    if (op === 'contains') {\n      return `json_contains(${jsonField}, ${toJsonValue(value)})`\n    }\n    throw new E_VECTOR_STORE_UNSUPPORTED_FILTER_OPERATOR(['milvus', op])\n  }\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n    const parts: string[] = []\n    if (and) {\n      const children = and.map((f) => translateMilvusFilter(f)).filter((c) => c !== '')\n      if (children.length === 0) return ''\n      if (children.length === 1) return children[0]\n      parts.push(`(${children.join(' && ')})`)\n    }\n    if (or) {\n      const children = or.map((f) => translateMilvusFilter(f)).filter((c) => c !== '')\n      if (children.length === 0) return ''\n      if (children.length === 1) return children[0]\n      parts.push(`(${children.join(' || ')})`)\n    }\n    if (not) {\n      const child = translateMilvusFilter(not)\n      if (child === '') return ''\n      parts.push(`!(${child})`)\n    }\n    if (parts.length === 0) return ''\n    if (parts.length === 1) return parts[0]\n    return parts.join(' && ')\n  }\n  return ''\n}\n"],"mappings":";;;;;;;;;AAiCA,IAAM,kBAAkB,YAAY;CAClC,IAAI;EAEF,QAAO,MADW,OAAO,6BACd;CACb,QAAQ;EACN,MAAM,IAAI,kCAAkC,CAAC,0BAA0B,CAAC;CAC1E;AACF;AAEA,IAAM,cAAc,YAAY;CAC9B,IAAI;EAEF,QAAO,MADW,OAAO,6BACd;CACb,QAAQ;EACN,MAAM,IAAI,kCAAkC,CAAC,0BAA0B,CAAC;CAC1E;AACF;AAEA,IAAM,qBAAqB,WAA2B;CACpD,IAAI,WAAW,UAAU,OAAO;CAChC,IAAI,WAAW,OAAO,OAAO;CAC7B,IAAI,WAAW,aAAa,OAAO;CACnC,OAAO;AACT;AAEA,IAAa,oBAAb,cAAuC,gBAAgB;CACrD,eAAiD;EAC/C,cAAc;EACd,cAAc;EACd,QAAQ;EACR,QAAQ;EACR,iBAAiB;EAEjB,aAAa;GAAE,cAAc;GAAO,SAAS;GAAU,OAAO,CAAC,QAAQ;EAAE;CAC3E;CACA,UAAsB;CACtB,wBAA6B,IAAI,IAAI;CACrC,IAAIA,QAAQ;EACV,OAAO,KAAK;CACd;CACA,OAAO,cAAuB;EAC5B,OAAO,OAAO,YAAY;CAC5B;CACA,cAAuB;EACrB,OAAO,OAAO,YAAY;CAC5B;CACA,MAAM,UAAyB;EAC7B,IAAI,KAAKC,SAAS;EAClB,MAAM,eAAe,MAAM,gBAAgB;EAC3C,MAAM,IAAI,KAAKD,MAAM,cAAc,CAAC;EACpC,IAAI,UAAU,EAAE;EAChB,IAAI,CAAC,WAAW,EAAE,KAChB,IAAI;GACF,MAAM,MAAM,IAAI,IAAI,EAAE,GAAG;GAGzB,UAAU,GAFG,IAAI,SAEC,GADL,IAAI,SAAS,IAAI,aAAa,WAAW,QAAQ;EAEhE,QAAQ;GACN,MAAM,IAAI,iCAAiC,CAAC,wBAAwB,CAAC;EACvE;EAEF,IAAI,CAAC,SACH,UAAU;EAEZ,IAAI;GACF,KAAKC,UAAU,IAAI,aAAa;IAC9B;IACA,OAAO,EAAE;IACT,UAAU,EAAE;IACZ,UAAU,EAAE;IACZ,KAAK,EAAE;GACT,CAAC;EACH,SAAS,KAAK;GACZ,MAAM,IAAI,iCAAiC,CAAC,OAAO,GAAG,CAAC,CAAC;EAC1D;CACF;CACA,MAAM,QAAuB;EAC3B,IAAI,KAAKA,SAAS;GAChB,MAAM,KAAKA,QAAQ,kBAAkB;GACrC,KAAKA,UAAU;EACjB;CACF;CACA,MAAM,iBAAiB,MAAsB,aAAqC;EAChF,MAAM,SAAS,KAAKA,YAAY,MAAM,KAAK,QAAQ,GAAG,KAAKA;EAC3D,MAAM,iBAAiB,KAAK;EAC5B,MAAM,SAAS,KAAK,OAAO,UAAU;EACrC,MAAM,MAAM,KAAK,OAAO;EACxB,IAAI,eAAgB,MAAM,KAAK,cAAc,cAAc,GAAI;EAC/D,IAAI;GACF,MAAM,MAAM,MAAM,OAAO,cAAc,EAAE,iBAAiB,eAAe,CAAC;GAC1E,IAAI,IAAI,SAAS,CAAC,aAChB,MAAM,IAAI,iCAAiC,CAAC,UAAU,mBAAmB,CAAC;GAE5E,IAAI,IAAI,SAAS,aAAa;GAC9B,MAAM,WAAW,MAAM,YAAY;GACnC,MAAM,OAAO,iBAAiB;IAC5B,iBAAiB;IACjB,QAAQ;KACN;MAAE,MAAM;MAAM,WAAW,SAAS;MAAS,gBAAgB;MAAM,YAAY;KAAI;KACjF;MAAE,MAAM;MAAU,WAAW,SAAS;MAAa;KAAI;KACvD;MAAE,MAAM;MAAY,WAAW,SAAS;MAAS,YAAY;KAAM;KACnE;MAAE,MAAM;MAAY,WAAW,SAAS;KAAK;IAC/C;GACF,CAAC;GACD,MAAM,YAAY;GAClB,MAAM,aAAa,kBAAkB,MAAM;GAC3C,MAAM,OAAO,YAAY;IACvB,iBAAiB;IACjB,YAAY;IACZ,YAAY;IACZ,aAAa;GACf,CAAC;GACD,MAAM,OAAO,mBAAmB,EAAE,iBAAiB,eAAe,CAAC;GACnE,KAAKC,MAAM,IAAI,gBAAgB,GAAG;EACpC,SAAS,KAAK;GACZ,MAAM,IAAI,iCAAiC,CAAC,oBAAoB,OAAO,GAAG,CAAC,CAAC;EAC9E;CACF;CACA,MAAM,eAAe,YAAoB,UAAkC;EACzE,MAAM,SAAS,KAAKD,YAAY,MAAM,KAAK,QAAQ,GAAG,KAAKA;EAC3D,IAAI,YAAY,CAAE,MAAM,KAAK,cAAc,UAAU,GAAI;EACzD,IAAI;GAEF,IAAI,EAAC,MADa,OAAO,cAAc,EAAE,iBAAiB,WAAW,CAAC,GAC7D,SAAS,CAAC,UACjB,MAAM,IAAI,iCAAiC,CAAC,QAAQ,2BAA2B,CAAC;GAElF,MAAM,OAAO,eAAe,EAAE,iBAAiB,WAAW,CAAC;GAC3D,KAAKC,MAAM,OAAO,UAAU;EAC9B,SAAS,KAAK;GACZ,MAAM,IAAI,iCAAiC,CAAC,kBAAkB,OAAO,GAAG,CAAC,CAAC;EAC5E;CACF;CACA,MAAM,cAAc,YAAsC;EACxD,MAAM,SAAS,KAAKD,YAAY,MAAM,KAAK,QAAQ,GAAG,KAAKA;EAC3D,IAAI;GAEF,OAAO,CAAC,EAAC,MADO,OAAO,cAAc,EAAE,iBAAiB,WAAW,CAAC,GACzD;EACb,QAAQ;GACN,OAAO;EACT;CACF;CACA,MAAM,iBAAiB,MAAc,IAA2B;EAC9D,MAAM,SAAS,KAAKA,YAAY,MAAM,KAAK,QAAQ,GAAG,KAAKA;EAC3D,IAAI;GACF,MAAM,OAAO,iBAAiB;IAAE,qBAAqB;IAAM,qBAAqB;GAAG,CAAC;GACpF,IAAI,KAAKC,MAAM,IAAI,IAAI,GAAG;IACxB,KAAKA,MAAM,IAAI,IAAI,KAAKA,MAAM,IAAI,IAAI,CAAE;IACxC,KAAKA,MAAM,OAAO,IAAI;GACxB;EACF,SAAS,KAAK;GACZ,MAAM,IAAI,iCAAiC,CAAC,oBAAoB,OAAO,GAAG,CAAC,CAAC;EAC9E;CACF;CACA,MAAM,cAAc,MAAiC;EACnD,IAAI,KAAK,QAAQ,WAAW,GAAG;EAC/B,gBAAgB,KAAK,OAAO;EAC5B,MAAM,SAAS,KAAKD,YAAY,MAAM,KAAK,QAAQ,GAAG,KAAKA;EAC3D,MAAM,iBAAiB,KAAK;EAC5B,MAAM,MAAM,KAAKC,MAAM,IAAI,cAAc;EACzC,MAAM,OAAc,CAAC;EACrB,KAAK,MAAM,KAAK,KAAK,SAAS;GAC5B,IAAI,SAAS,EAAE;GACf,IAAI,CAAC,UAAU,EAAE,UAAU;IACzB,MAAM,CAAC,KAAK,MAAM,KAAK,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU;IACtD,SAAS;GACX;GACA,IAAI,CAAC,QACH,MAAM,IAAI,6BAA6B,CAAC,oCAAoC,CAAC;GAE/E,IAAI,QAAQ,KAAA,KAAa,OAAO,WAAW,KACzC,MAAM,IAAI,kCAAkC,CAAC,KAAK,OAAO,MAAM,CAAC;GAElE,KAAK,KAAK;IACR,IAAI,EAAE;IACN;IACA,UAAU,EAAE,YAAY;IACxB,UAAU,EAAE,YAAY,CAAC;GAC3B,CAAC;EACH;EACA,IAAI;GACF,MAAM,OAAO,OAAO;IAAE,iBAAiB;IAAgB,MAAM;GAAK,CAAC;GACnE,MAAM,OAAO,UAAU,EAAE,kBAAkB,CAAC,cAAc,EAAE,CAAC;EAC/D,SAAS,KAAK;GACZ,MAAM,IAAI,6BAA6B,CAAC,OAAO,GAAG,CAAC,CAAC;EACtD;CACF;CACA,MAAM,cAAc,MAA0C;EAC5D,MAAM,SAAS,KAAKD,YAAY,MAAM,KAAK,QAAQ,GAAG,KAAKA;EAC3D,MAAM,SAAS,KAAKD,MAAM,UAAU;EACpC,IAAI;EACJ,IAAI,KAAK;OACH,YAAY,KAAK,MACnB,cAAc,KAAK,KAAK;QACnB,IAAI,gBAAgB,KAAK,MAAM;IACpC,MAAM,CAAC,KAAK,MAAM,KAAK,OAAO,CAAC,KAAK,KAAK,UAAU,GAAG,OAAO;IAC7D,cAAc;GAChB,OAAO,IAAI,QAAQ,KAAK,MAAM;IAC5B,MAAM,MAAM,MAAM,OAAO,MAAM;KAC7B,iBAAiB,KAAK;KACtB,QAAQ,UAAU,KAAK,KAAK,GAAG;KAC/B,eAAe,CAAC,QAAQ;IAC1B,CAAC;IACD,IAAI,IAAI,KAAK,WAAW,GACtB,MAAM,IAAI,6BAA6B,CAAC,8BAA8B,KAAK,KAAK,EAAE,CAAC;IAErF,cAAc,IAAI,KAAK,GAAG;GAC5B;;EAEF,MAAM,eAAe;GAAC;GAAM;GAAY;EAAU;EAClD,IAAI,KAAK,WAAW,QAClB,aAAa,KAAK,QAAQ;EAE5B,MAAM,eAAe,sBAAsB,KAAK,MAAM;EACtD,IAAI;EACJ,IAAI,aACF,UAAU,MAAM,OAAO,OAAO;GAC5B,iBAAiB,KAAK;GACtB,MAAM,CAAC,WAAW;GAClB,OAAO,KAAK;GACZ,QAAQ,KAAK;GACb,QAAQ;GACR,eAAe;GACf,mBAAmB;EACrB,CAAC;OAED,UAAU,MAAM,OAAO,MAAM;GAC3B,iBAAiB,KAAK;GACtB,QAAQ,gBAAgB;GACxB,OAAO,KAAK;GACZ,QAAQ,KAAK;GACb,eAAe;GACf,mBAAmB;EACrB,CAAC;EAEH,MAAM,UAAU,QAAQ,WAAW,QAAQ,QAAQ,CAAC;EACpD,MAAM,OAAO,KAAK;EAClB,OAAO,QAAQ,KAAK,QAAa,KAAK,WAAW,KAAK,MAAM,MAAM,CAAC;CACrE;CACA,MAAM,cAAc,MAAiC;EACnD,MAAM,SAAS,KAAKC,YAAY,MAAM,KAAK,QAAQ,GAAG,KAAKA;EAC3D,IAAI;GACF,MAAM,iBAAiB,KAAK;GAC5B,IAAI,KAAK,KAAK;IACZ,MAAM,SAAS,UAAU,KAAK,IAAI,KAAK,MAAM,KAAK,UAAU,CAAC,CAAC,EAAE,KAAK,GAAG,EAAE;IAC1E,MAAM,OAAO,OAAO;KAAE,iBAAiB;KAAgB;IAAO,CAAC;GACjE,OAAO,IAAI,KAAK,QAAQ;IACtB,MAAM,SAAS,sBAAsB,KAAK,MAAM;IAChD,MAAM,OAAO,OAAO;KAAE,iBAAiB;KAAgB;IAAO,CAAC;GACjE,OACE,MAAM,OAAO,OAAO;IAAE,iBAAiB;IAAgB,QAAQ;GAAW,CAAC;EAE/E,SAAS,KAAK;GACZ,MAAM,IAAI,6BAA6B,CAAC,OAAO,GAAG,CAAC,CAAC;EACtD;CACF;CACA,WAAW,KAAU,YAAiB,QAA6B;EACjE,MAAM,MAAmB,CAAC;EAC1B,IAAI,WAAW,IACb,IAAI,KAAK,IAAI;EAEf,IAAI,WAAW,UAAU,YAAY,KACnC,IAAI,SAAS,IAAI;EAEnB,IAAI,WAAW,UACb,IAAI,WAAW,IAAI;EAErB,IAAI,WAAW,UACb,IAAI,WAAW,IAAI;EAErB,IAAI,WAAW,OAAO,IAAI,UAAU,KAAA,GAAW;GAC7C,MAAM,OAAO,WAAW,cAAc,aAAa;GACnD,IAAI,QAAQ,eAAe,IAAI,OAAiB,QAAe,IAAI;EACrE;EACA,OAAO;CACT;CACA,sBAAsB,QAA+B;EACnD,OAAO,sBAAsB,MAAM;CACrC;AACF;AAEA,IAAa,yBAAyB,WAAkC;CACtE,IAAI,CAAC,QAAQ,OAAO;CACpB,IAAI,YAAY,MAAM,GAAG;EACvB,IAAI,OAAO,aAAa,YAAY,OAAO,OAAO,SAAS,UACzD,OAAO,OAAO;EAEhB,MAAM,IAAI,2CAA2C,CAAC,UAAU,OAAO,OAAO,QAAQ,CAAC,CAAC;CAC1F;CACA,IAAI,kBAAkB,MAAM,GAAG;EAC7B,MAAM,EAAE,OAAO,IAAI,UAAU;EAC7B,MAAM,YAAY,aAAa,MAAM;EACrC,IAAI,UAAU,KAAA,GAAW;GACvB,IAAI,OAAO,UACT,OAAO,UAAU;GAEnB,MAAM,IAAI,2CAA2C,CAAC,UAAU,EAAE,CAAC;EACrE;EACA,MAAM,eAAe,MAAuB;GAC1C,IAAI,OAAO,MAAM,UAAU,OAAO,KAAK,UAAU,CAAC;GAClD,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,WAAW,OAAO,OAAO,CAAC;GACpE,IAAI,MAAM,QAAQ,CAAC,GACjB,OAAO,IAAI,EAAE,IAAI,WAAW,EAAE,KAAK,GAAG,EAAE;GAE1C,OAAO,KAAK,UAAU,CAAC;EACzB;EACA,IAAI,OAAO,MAAM,OAAO,GAAG,UAAU,MAAM,YAAY,KAAK;EAC5D,IAAI,OAAO,MAAM,OAAO,GAAG,UAAU,MAAM,YAAY,KAAK;EAC5D,IAAI,OAAO,MAAM,OAAO,GAAG,UAAU,KAAK,YAAY,KAAK;EAC3D,IAAI,OAAO,OAAO,OAAO,GAAG,UAAU,MAAM,YAAY,KAAK;EAC7D,IAAI,OAAO,MAAM,OAAO,GAAG,UAAU,KAAK,YAAY,KAAK;EAC3D,IAAI,OAAO,OAAO,OAAO,GAAG,UAAU,MAAM,YAAY,KAAK;EAC7D,IAAI,OAAO,MAAM;GACf,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG,OAAO;GAClC,OAAO,GAAG,UAAU,OAAO,MAAM,IAAI,WAAW,EAAE,KAAK,GAAG,EAAE;EAC9D;EACA,IAAI,OAAO,OAAO;GAChB,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG,OAAO;GAClC,OAAO,GAAG,UAAU,WAAW,MAAM,IAAI,WAAW,EAAE,KAAK,GAAG,EAAE;EAClE;EACA,IAAI,OAAO,UACT,OAAO,UAAU;EAEnB,IAAI,OAAO,YACT,OAAO,iBAAiB,UAAU,IAAI,YAAY,KAAK,EAAE;EAE3D,MAAM,IAAI,2CAA2C,CAAC,UAAU,EAAE,CAAC;CACrE;CACA,IAAI,cAAc,MAAM,GAAG;EACzB,MAAM,EAAE,KAAK,IAAI,QAAQ;EACzB,MAAM,QAAkB,CAAC;EACzB,IAAI,KAAK;GACP,MAAM,WAAW,IAAI,KAAK,MAAM,sBAAsB,CAAC,CAAC,EAAE,QAAQ,MAAM,MAAM,EAAE;GAChF,IAAI,SAAS,WAAW,GAAG,OAAO;GAClC,IAAI,SAAS,WAAW,GAAG,OAAO,SAAS;GAC3C,MAAM,KAAK,IAAI,SAAS,KAAK,MAAM,EAAE,EAAE;EACzC;EACA,IAAI,IAAI;GACN,MAAM,WAAW,GAAG,KAAK,MAAM,sBAAsB,CAAC,CAAC,EAAE,QAAQ,MAAM,MAAM,EAAE;GAC/E,IAAI,SAAS,WAAW,GAAG,OAAO;GAClC,IAAI,SAAS,WAAW,GAAG,OAAO,SAAS;GAC3C,MAAM,KAAK,IAAI,SAAS,KAAK,MAAM,EAAE,EAAE;EACzC;EACA,IAAI,KAAK;GACP,MAAM,QAAQ,sBAAsB,GAAG;GACvC,IAAI,UAAU,IAAI,OAAO;GACzB,MAAM,KAAK,KAAK,MAAM,EAAE;EAC1B;EACA,IAAI,MAAM,WAAW,GAAG,OAAO;EAC/B,IAAI,MAAM,WAAW,GAAG,OAAO,MAAM;EACrC,OAAO,MAAM,KAAK,MAAM;CAC1B;CACA,OAAO;AACT"}

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

@@ -0,0 +1,46 @@
+/**
+ * @module @nhtio/adk/batteries/vector/mongodb
+ *
+ * MongoDB Atlas Vector Search adapter. Each collection is a MongoDB collection with an Atlas
+ * `vectorSearch` index on `vec`; KNN uses the `$vectorSearch` aggregation stage (cosine
+ * `vectorSearchScore`, [0,1]). Metadata is a JSON string field filtered with the neutral filter
+ * tree's JS reference evaluator for cross-adapter parity.
+ *
+ * Consistency note: the *document* collection is strongly consistent, but the Atlas vector
+ * *index* updates asynchronously after a write (~1s). So filter-scans, fetch-by-id and the
+ * delete read-back use a plain `find()` (immediate), and only KNN goes through `$vectorSearch` —
+ * after which the adapter polls until the just-inserted ids are index-visible (strong mode).
+ *
+ * Driver: `mongodb`. Works against `mongodb/mongodb-atlas-local` or a real Atlas cluster.
+ */
+import { BaseVectorStore } from "../contract";
+import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
+import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
+export interface MongoDBVectorStoreOptions extends BaseVectorStoreOptions {
+    connection: {
+        url: string;
+        database?: string;
+        /**
+         * When set, the physical MongoDB collection becomes `${collectionPrefix}${collection}`. The
+         * logical collection the builder/base see is unchanged. Lets callers (and the test suite)
+         * isolate otherwise identically-named collections — useful because the Atlas vectorSearch
+         * index builds asynchronously, so a fresh collection per use avoids drop+rebuild churn.
+         */
+        collectionPrefix?: string;
+    };
+}
+export declare class MongoDBVectorStore 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>;
+}