@nhtio/adk 1.20260604.0 → 1.20260607.0

package/batteries/vector/surrealdb.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"surrealdb.cjs","names":["#opts","#db","#ensure","#query","#dims","#norm","#parseMeta","#project"],"sources":["../../../src/batteries/vector/surrealdb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/surrealdb\n *\n * SurrealDB adapter (multi-model). Each collection is a SurrealDB table; records store the\n * vector as a plain array field and KNN uses `vector::similarity::cosine` /\n * `vector::distance::euclidean` ordered appropriately. Metadata is a JSON string field filtered\n * with the neutral filter tree's JS reference evaluator for exact cross-adapter parity.\n *\n * Driver: `surrealdb` (pure JS). All queries are parameterized via `$bindings`.\n */\n\nimport { evaluateFilter } from '../filters'\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} from '../types'\n\nexport interface SurrealDBVectorStoreOptions extends BaseVectorStoreOptions {\n  connection: {\n    url: string\n    username?: string\n    password?: string\n    namespace?: string\n    database?: string\n  }\n}\n\nconst getSurreal = async () => {\n  try {\n    const mod = await import('surrealdb')\n    return mod.Surreal\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['surrealdb'])\n  }\n}\n\n// Backtick-quoted SurrealQL identifier.\nconst ident = (name: string): string => '`' + name.replace(/`/g, '\\\\`') + '`'\n\n// Extract the bare id from a SurrealDB RecordId (object with .id) or a \"table:id\" string.\nconst recordIdToString = (rid: unknown): string => {\n  if (rid && typeof rid === 'object' && 'id' in (rid as any)) {\n    return String((rid as any).id)\n  }\n  const s = String(rid)\n  const idx = s.indexOf(':')\n  return idx >= 0 ? s.slice(idx + 1).replace(/^⟨|⟩$/g, '') : s\n}\n\nexport class SurrealDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Synchronous over the RPC connection: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #db: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): SurrealDBVectorStoreOptions {\n    return this.options as SurrealDBVectorStoreOptions\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.#db) return\n    const Surreal = await getSurreal()\n    const c = this.#opts.connection\n    try {\n      this.#db = new Surreal()\n      const rpc = c.url.replace(/\\/$/, '')\n      await this.#db.connect(rpc.endsWith('/rpc') ? rpc : `${rpc}/rpc`)\n      if (c.username) {\n        await this.#db.signin({ username: c.username, password: c.password ?? '' })\n      }\n      await this.#db.use({ namespace: c.namespace ?? 'test', database: c.database ?? 'test' })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#db) {\n      await this.#db.close()\n      this.#db = null\n    }\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#db) await this.connect()\n    return this.#db!\n  }\n\n  async #query(sql: string, vars?: Record<string, unknown>): Promise<any[]> {\n    const db = await this.#ensure()\n    const res = await db.query(sql, vars)\n    return res as any[]\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await this.#query(`DEFINE TABLE ${ine}${ident(spec.collection)} SCHEMALESS;`)\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 ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await this.#query(`REMOVE 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    try {\n      const res = await this.#query('INFO FOR DB;')\n      const info = res[0]\n      const tables = info?.tables ?? info?.tb ?? {}\n      return Object.prototype.hasOwnProperty.call(tables, collection)\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(_from: string, _to: string): Promise<void> {\n    throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'surrealdb'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\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        await this.#query(\n          `UPSERT type::thing($tbl, $rid) SET vec = $vec, document = $document, metadata = $metadata;`,\n          {\n            tbl: plan.collection,\n            rid: r.id,\n            vec: vector,\n            document: r.document ?? '',\n            metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n          }\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 res = await this.#query(`SELECT vec FROM type::thing($tbl, $rid);`, {\n          tbl: plan.collection,\n          rid: plan.near.id,\n        })\n        const row = res[0]?.[0]\n        if (!row) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = row.vec as number[]\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      const tbl = ident(plan.collection)\n      let rows: any[]\n      if (queryVector) {\n        // similarity::cosine (higher=better) for cosine/dot; distance::euclidean (lower=better) for l2.\n        const useDistance = metric === 'euclidean'\n        const fn = useDistance ? 'vector::distance::euclidean' : 'vector::similarity::cosine'\n        const order = useDistance ? 'ASC' : 'DESC'\n        const res = await this.#query(\n          `SELECT *, ${fn}(vec, $qv) AS __score FROM ${tbl} ORDER BY __score ${order};`,\n          { qv: queryVector }\n        )\n        rows = res[0] ?? []\n        const scored = rows.map((row) => ({ row, score: this.#norm(Number(row.__score), metric) }))\n        const filtered = plan.filter\n          ? scored.filter((s) => evaluateFilter(plan.filter!, this.#parseMeta(s.row.metadata)))\n          : scored\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((s) => this.#project(s.row, plan, s.score))\n      } else {\n        const res = await this.#query(`SELECT * FROM ${tbl};`)\n        rows = res[0] ?? []\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, undefined))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  // cosine similarity is already [-1,1]; map to [0,1]. euclidean distance → 1/(1+d).\n  #norm(raw: number, metric: string): number {\n    if (metric === 'euclidean') return 1 / (1 + raw)\n    return (raw + 1) / 2\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, score: number | undefined): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = recordIdToString(row.id)\n    if (proj.vector && Array.isArray(row.vec)) out.vector = (row.vec as number[]).map(Number)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (score !== undefined && !Number.isNaN(score)) out.score = score\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        for (const id of plan.ids) {\n          await this.#query(`DELETE type::thing($tbl, $rid);`, { tbl: plan.collection, rid: id })\n        }\n      } else if (plan.filter) {\n        const res = await this.#query(`SELECT id, metadata FROM ${ident(plan.collection)};`)\n        const rows = res[0] ?? []\n        const targets = rows\n          .filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row: any) => recordIdToString(row.id))\n        for (const id of targets) {\n          await this.#query(`DELETE type::thing($tbl, $rid);`, { tbl: plan.collection, rid: id })\n        }\n      } else {\n        await this.#query(`DELETE ${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/surrealdb.mjs

@@ -0,0 +1,228 @@
+import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import "../../guards.mjs";
+import { evaluateFilter } from "./filters.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/surrealdb/index.ts
+/**
+* @module @nhtio/adk/batteries/vector/surrealdb
+*
+* SurrealDB adapter (multi-model). Each collection is a SurrealDB table; records store the
+* vector as a plain array field and KNN uses `vector::similarity::cosine` /
+* `vector::distance::euclidean` ordered appropriately. Metadata is a JSON string field filtered
+* with the neutral filter tree's JS reference evaluator for exact cross-adapter parity.
+*
+* Driver: `surrealdb` (pure JS). All queries are parameterized via `$bindings`.
+*/
+var getSurreal = async () => {
+	try {
+		return (await import("surrealdb")).Surreal;
+	} catch {
+		throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(["surrealdb"]);
+	}
+};
+var ident = (name) => "`" + name.replace(/`/g, "\\`") + "`";
+var recordIdToString = (rid) => {
+	if (rid && typeof rid === "object" && "id" in rid) return String(rid.id);
+	const s = String(rid);
+	const idx = s.indexOf(":");
+	return idx >= 0 ? s.slice(idx + 1).replace(/^⟨|⟩$/g, "") : s;
+};
+var SurrealDBVectorStore = class extends BaseVectorStore {
+	capabilities = {
+		transactions: false,
+		namedVectors: false,
+		rename: false,
+		rawSql: false,
+		builtInEncoding: false,
+		consistency: {
+			configurable: false,
+			default: "strong",
+			modes: ["strong"]
+		}
+	};
+	#db = 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.#db) return;
+		const Surreal = await getSurreal();
+		const c = this.#opts.connection;
+		try {
+			this.#db = new Surreal();
+			const rpc = c.url.replace(/\/$/, "");
+			await this.#db.connect(rpc.endsWith("/rpc") ? rpc : `${rpc}/rpc`);
+			if (c.username) await this.#db.signin({
+				username: c.username,
+				password: c.password ?? ""
+			});
+			await this.#db.use({
+				namespace: c.namespace ?? "test",
+				database: c.database ?? "test"
+			});
+		} catch (err) {
+			throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)]);
+		}
+	}
+	async close() {
+		if (this.#db) {
+			await this.#db.close();
+			this.#db = null;
+		}
+	}
+	async #ensure() {
+		if (!this.#db) await this.connect();
+		return this.#db;
+	}
+	async #query(sql, vars) {
+		return await (await this.#ensure()).query(sql, vars);
+	}
+	async createCollection(spec, ifNotExists) {
+		this.#dims.set(spec.collection, spec.vector.dimensions);
+		const ine = ifNotExists ? "IF NOT EXISTS " : "";
+		try {
+			await this.#query(`DEFINE TABLE ${ine}${ident(spec.collection)} SCHEMALESS;`);
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["createCollection", String(err)]);
+		}
+	}
+	async dropCollection(collection, ifExists) {
+		const ie = ifExists ? "IF EXISTS " : "";
+		try {
+			await this.#query(`REMOVE TABLE ${ie}${ident(collection)};`);
+			this.#dims.delete(collection);
+		} catch (err) {
+			throw new E_VECTOR_STORE_COLLECTION_FAILED(["dropCollection", String(err)]);
+		}
+	}
+	async hasCollection(collection) {
+		try {
+			const info = (await this.#query("INFO FOR DB;"))[0];
+			const tables = info?.tables ?? info?.tb ?? {};
+			return Object.prototype.hasOwnProperty.call(tables, collection);
+		} catch {
+			return false;
+		}
+	}
+	async renameCollection(_from, _to) {
+		throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(["renameCollection", "surrealdb"]);
+	}
+	async executeUpsert(plan) {
+		if (plan.records.length === 0) return;
+		validateRecords(plan.records);
+		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]);
+				await this.#query(`UPSERT type::thing($tbl, $rid) SET vec = $vec, document = $document, metadata = $metadata;`, {
+					tbl: plan.collection,
+					rid: r.id,
+					vec: vector,
+					document: r.document ?? "",
+					metadata: r.metadata ? JSON.stringify(r.metadata) : "{}"
+				});
+			}
+		} 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 row = (await this.#query(`SELECT vec FROM type::thing($tbl, $rid);`, {
+					tbl: plan.collection,
+					rid: plan.near.id
+				}))[0]?.[0];
+				if (!row) throw new E_VECTOR_STORE_SEARCH_FAILED(["Referenced id not found: " + plan.near.id]);
+				queryVector = row.vec;
+			}
+		}
+		const offset = plan.offset ?? 0;
+		try {
+			const tbl = ident(plan.collection);
+			let rows;
+			if (queryVector) {
+				const useDistance = metric === "euclidean";
+				const fn = useDistance ? "vector::distance::euclidean" : "vector::similarity::cosine";
+				const order = useDistance ? "ASC" : "DESC";
+				rows = (await this.#query(`SELECT *, ${fn}(vec, $qv) AS __score FROM ${tbl} ORDER BY __score ${order};`, { qv: queryVector }))[0] ?? [];
+				const scored = rows.map((row) => ({
+					row,
+					score: this.#norm(Number(row.__score), metric)
+				}));
+				return (plan.filter ? scored.filter((s) => evaluateFilter(plan.filter, this.#parseMeta(s.row.metadata))) : scored).slice(offset, offset + plan.topK).map((s) => this.#project(s.row, plan, s.score));
+			} else {
+				rows = (await this.#query(`SELECT * FROM ${tbl};`))[0] ?? [];
+				return (plan.filter ? rows.filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row.metadata))) : rows).slice(offset, offset + plan.topK).map((row) => this.#project(row, plan, void 0));
+			}
+		} catch (err) {
+			throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)]);
+		}
+	}
+	#norm(raw, metric) {
+		if (metric === "euclidean") return 1 / (1 + raw);
+		return (raw + 1) / 2;
+	}
+	#parseMeta(val) {
+		if (typeof val === "string") try {
+			return JSON.parse(val);
+		} catch {
+			return {};
+		}
+		if (val && typeof val === "object") return val;
+		return {};
+	}
+	#project(row, plan, score) {
+		const proj = plan.projection;
+		const out = {};
+		if (proj.id) out.id = recordIdToString(row.id);
+		if (proj.vector && Array.isArray(row.vec)) out.vector = row.vec.map(Number);
+		if (proj.document) out.document = row.document ?? void 0;
+		if (proj.metadata) out.metadata = this.#parseMeta(row.metadata);
+		if (score !== void 0 && !Number.isNaN(score)) out.score = score;
+		return out;
+	}
+	async executeDelete(plan) {
+		try {
+			if (plan.ids && plan.ids.length > 0) for (const id of plan.ids) await this.#query(`DELETE type::thing($tbl, $rid);`, {
+				tbl: plan.collection,
+				rid: id
+			});
+			else if (plan.filter) {
+				const targets = ((await this.#query(`SELECT id, metadata FROM ${ident(plan.collection)};`))[0] ?? []).filter((row) => evaluateFilter(plan.filter, this.#parseMeta(row.metadata))).map((row) => recordIdToString(row.id));
+				for (const id of targets) await this.#query(`DELETE type::thing($tbl, $rid);`, {
+					tbl: plan.collection,
+					rid: id
+				});
+			} else await this.#query(`DELETE ${ident(plan.collection)};`);
+		} catch (err) {
+			throw new E_VECTOR_STORE_DELETE_FAILED([String(err)]);
+		}
+	}
+};
+//#endregion
+export { SurrealDBVectorStore };
+
+//# sourceMappingURL=surrealdb.mjs.map

package/batteries/vector/surrealdb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"surrealdb.mjs","names":["#opts","#db","#ensure","#query","#dims","#norm","#parseMeta","#project"],"sources":["../../../src/batteries/vector/surrealdb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/surrealdb\n *\n * SurrealDB adapter (multi-model). Each collection is a SurrealDB table; records store the\n * vector as a plain array field and KNN uses `vector::similarity::cosine` /\n * `vector::distance::euclidean` ordered appropriately. Metadata is a JSON string field filtered\n * with the neutral filter tree's JS reference evaluator for exact cross-adapter parity.\n *\n * Driver: `surrealdb` (pure JS). All queries are parameterized via `$bindings`.\n */\n\nimport { evaluateFilter } from '../filters'\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} from '../types'\n\nexport interface SurrealDBVectorStoreOptions extends BaseVectorStoreOptions {\n  connection: {\n    url: string\n    username?: string\n    password?: string\n    namespace?: string\n    database?: string\n  }\n}\n\nconst getSurreal = async () => {\n  try {\n    const mod = await import('surrealdb')\n    return mod.Surreal\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['surrealdb'])\n  }\n}\n\n// Backtick-quoted SurrealQL identifier.\nconst ident = (name: string): string => '`' + name.replace(/`/g, '\\\\`') + '`'\n\n// Extract the bare id from a SurrealDB RecordId (object with .id) or a \"table:id\" string.\nconst recordIdToString = (rid: unknown): string => {\n  if (rid && typeof rid === 'object' && 'id' in (rid as any)) {\n    return String((rid as any).id)\n  }\n  const s = String(rid)\n  const idx = s.indexOf(':')\n  return idx >= 0 ? s.slice(idx + 1).replace(/^⟨|⟩$/g, '') : s\n}\n\nexport class SurrealDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Synchronous over the RPC connection: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #db: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): SurrealDBVectorStoreOptions {\n    return this.options as SurrealDBVectorStoreOptions\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.#db) return\n    const Surreal = await getSurreal()\n    const c = this.#opts.connection\n    try {\n      this.#db = new Surreal()\n      const rpc = c.url.replace(/\\/$/, '')\n      await this.#db.connect(rpc.endsWith('/rpc') ? rpc : `${rpc}/rpc`)\n      if (c.username) {\n        await this.#db.signin({ username: c.username, password: c.password ?? '' })\n      }\n      await this.#db.use({ namespace: c.namespace ?? 'test', database: c.database ?? 'test' })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#db) {\n      await this.#db.close()\n      this.#db = null\n    }\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#db) await this.connect()\n    return this.#db!\n  }\n\n  async #query(sql: string, vars?: Record<string, unknown>): Promise<any[]> {\n    const db = await this.#ensure()\n    const res = await db.query(sql, vars)\n    return res as any[]\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await this.#query(`DEFINE TABLE ${ine}${ident(spec.collection)} SCHEMALESS;`)\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 ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await this.#query(`REMOVE 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    try {\n      const res = await this.#query('INFO FOR DB;')\n      const info = res[0]\n      const tables = info?.tables ?? info?.tb ?? {}\n      return Object.prototype.hasOwnProperty.call(tables, collection)\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(_from: string, _to: string): Promise<void> {\n    throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'surrealdb'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\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        await this.#query(\n          `UPSERT type::thing($tbl, $rid) SET vec = $vec, document = $document, metadata = $metadata;`,\n          {\n            tbl: plan.collection,\n            rid: r.id,\n            vec: vector,\n            document: r.document ?? '',\n            metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n          }\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 res = await this.#query(`SELECT vec FROM type::thing($tbl, $rid);`, {\n          tbl: plan.collection,\n          rid: plan.near.id,\n        })\n        const row = res[0]?.[0]\n        if (!row) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = row.vec as number[]\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      const tbl = ident(plan.collection)\n      let rows: any[]\n      if (queryVector) {\n        // similarity::cosine (higher=better) for cosine/dot; distance::euclidean (lower=better) for l2.\n        const useDistance = metric === 'euclidean'\n        const fn = useDistance ? 'vector::distance::euclidean' : 'vector::similarity::cosine'\n        const order = useDistance ? 'ASC' : 'DESC'\n        const res = await this.#query(\n          `SELECT *, ${fn}(vec, $qv) AS __score FROM ${tbl} ORDER BY __score ${order};`,\n          { qv: queryVector }\n        )\n        rows = res[0] ?? []\n        const scored = rows.map((row) => ({ row, score: this.#norm(Number(row.__score), metric) }))\n        const filtered = plan.filter\n          ? scored.filter((s) => evaluateFilter(plan.filter!, this.#parseMeta(s.row.metadata)))\n          : scored\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((s) => this.#project(s.row, plan, s.score))\n      } else {\n        const res = await this.#query(`SELECT * FROM ${tbl};`)\n        rows = res[0] ?? []\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, undefined))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  // cosine similarity is already [-1,1]; map to [0,1]. euclidean distance → 1/(1+d).\n  #norm(raw: number, metric: string): number {\n    if (metric === 'euclidean') return 1 / (1 + raw)\n    return (raw + 1) / 2\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, score: number | undefined): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = recordIdToString(row.id)\n    if (proj.vector && Array.isArray(row.vec)) out.vector = (row.vec as number[]).map(Number)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (score !== undefined && !Number.isNaN(score)) out.score = score\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        for (const id of plan.ids) {\n          await this.#query(`DELETE type::thing($tbl, $rid);`, { tbl: plan.collection, rid: id })\n        }\n      } else if (plan.filter) {\n        const res = await this.#query(`SELECT id, metadata FROM ${ident(plan.collection)};`)\n        const rows = res[0] ?? []\n        const targets = rows\n          .filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row: any) => recordIdToString(row.id))\n        for (const id of targets) {\n          await this.#query(`DELETE type::thing($tbl, $rid);`, { tbl: plan.collection, rid: id })\n        }\n      } else {\n        await this.#query(`DELETE ${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/types.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");

package/batteries/vector/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Type definitions for the vector storage provider battery.
+ *
+ * @module @nhtio/adk/batteries/vector/types
+ *
+ * @remarks
+ * This module owns the shared types and interfaces used by all vector storage adapters.
+ * It defines the core abstractions for vectors, metadata, search results, and adapter
+ * capabilities without any runtime logic or driver dependencies.
+ */
+/** Metric used to compare vectors during similarity search. */
+export type DistanceMetric = 'cosine' | 'dot' | 'euclidean';
+/** A metadata value may be a primitive, null, or a nested object/array of such values. */
+export type VectorMetadataValue = string | number | boolean | null | VectorMetadataValue[] | {
+    [k: string]: VectorMetadataValue;
+};
+/** A flat or nested object mapping metadata keys to values. */
+export type VectorMetadata = Record<string, VectorMetadataValue>;
+/** A stored vector record. All fields are optional; at minimum, an id is required. */
+export interface VectorRecord {
+    id: string;
+    vector?: number[];
+    document?: string;
+    metadata?: VectorMetadata;
+}
+/** A result row from a vector search or filter scan. All fields are opt-in via .select(). */
+export interface VectorMatch {
+    id?: string;
+    score?: number;
+    metadata?: VectorMetadata;
+    document?: string;
+    vector?: number[];
+}
+/** Input to the encoder: either a raw vector array or raw text to be embedded. */
+export type VectorInput = number[] | {
+    text: string;
+};
+/** Indicates whether text is being encoded as a query or as a document. */
+export type EncodeKind = 'query' | 'document';
+/** The BYO text-to-vector contract. Batch-shaped: one round-trip for many texts. */
+export type VectorEncoderFn = (texts: string[], kind: EncodeKind) => Promise<number[][]>;
+/** Fixed per-adapter capability flags (static truth about a backend). */
+/**
+ * Read-after-write guarantee a write (`.upsert()` / `.delete()`) provides.
+ *   'strong'      — the write Promise does not resolve until the change is confirmed
+ *                   visible to subsequent reads. On timeout it THROWS
+ *                   `E_VECTOR_STORE_CONSISTENCY_TIMEOUT` — never resolves unconfirmed.
+ *   'best-effort' — poll up to the bound, then resolve whether or not visibility was
+ *                   confirmed. The ONLY mode that may proceed unconfirmed, and only
+ *                   because the caller asked for it. NOTE: on an eventually-consistent
+ *                   backend a write-after-write race (e.g. deleting a just-upserted id
+ *                   from a concurrent writer) may not take effect — this mode does not
+ *                   detect it. Use 'strong' if you delete records you may have just written.
+ *   'eventual'    — resolve on durable acknowledgement, with no visibility wait. Fastest;
+ *                   inherits the same write-after-write race as 'best-effort', silently.
+ */
+export type VectorConsistency = 'strong' | 'best-effort' | 'eventual';
+/**
+ * How an adapter handles the {@link VectorConsistency} option.
+ *   configurable:false → the backend is already strongly consistent (pgvector, sqlite-vec,
+ *     in-memory, orama, …); the option is a no-op and `default` is always 'strong'.
+ *   configurable:true  → an eventually-consistent backend (Pinecone today; ElasticSearch /
+ *     OpenSearch, Mongo Atlas Vector Search, multi-node Weaviate later) that honors the
+ *     option. `default` is what applies when neither a per-operation `.consistency()` nor a
+ *     store-level `consistency` option is set; `modes` enumerates what it accepts.
+ */
+export interface VectorConsistencyCapability {
+    configurable: boolean;
+    default: VectorConsistency;
+    modes: VectorConsistency[];
+}
+export interface VectorStoreCapabilities {
+    transactions: boolean;
+    namedVectors: boolean;
+    rename: boolean;
+    rawSql: boolean;
+    builtInEncoding: boolean;
+    consistency: VectorConsistencyCapability;
+}
+/** Shared base options every adapter extends with its own connection block. */
+export interface BaseVectorStoreOptions {
+    metric?: DistanceMetric;
+    encoder?: VectorEncoderFn;
+    dimensions?: number;
+    defaultCollection?: string;
+    /**
+     * Store-wide read-after-write guarantee for writes. Overrides the adapter's declared
+     * {@link VectorStoreCapabilities.consistency} default; a per-operation `.consistency()`
+     * on the builder overrides this in turn (precedence: per-op > store option > adapter
+     * default). Ignored by strongly-consistent adapters. See {@link VectorConsistency}.
+     */
+    consistency?: VectorConsistency;
+}
+/** Options for ensuring a collection exists. */
+export interface EnsureCollectionOptions {
+    collection: string;
+    dimensions: number;
+    metric?: DistanceMetric;
+    ifNotExists?: boolean;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * @module @nhtio/adk/batteries/vector/typesense
+ *
+ * Typesense adapter. Each collection is a Typesense collection with a `float[]` vector field
+ * (native `vector_query` KNN). Metadata is stored as a JSON string field and filtered with
+ * the neutral filter tree's JS reference evaluator for exact cross-adapter parity (Typesense
+ * filter_by requires per-field schema declaration, which the neutral metadata model doesn't
+ * have). Document + id are plain fields.
+ *
+ * Driver: `typesense` (pure JS).
+ */
+import { BaseVectorStore } from "../contract";
+import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
+import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
+export interface TypesenseVectorStoreOptions extends BaseVectorStoreOptions {
+    connection?: {
+        host?: string;
+        port?: number;
+        protocol?: string;
+        apiKey?: string;
+        url?: string;
+    };
+}
+export declare class TypesenseVectorStore 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>;
+}