@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.419

package/vector/contract.mjs

@@ -0,0 +1,635 @@
+import { p as VectorError } from "../schema-DS8x1Dn8.mjs";
+import { vectorDb } from "./index.mjs";
+//#region src/vector/contract.ts
+/**
+* Vector DB's contract: what every engine promises, as cases any test runner can run. The Stand-in
+* runs them in this package; the real Capability runs the same cases against its own engine,
+* through the wire. A behaviour that is not a case here is not promised.
+*
+*   for (const c of vectorContract) test(c.name, () => c.run(makeEngine()))
+*
+* Each case gets an engine with no namespaces in it, makes the ones it needs, and throws when the
+* engine breaks the promise. Expected values are worked out by hand, never computed with the SDK's
+* own code.
+*/
+const points = [
+	{
+		id: "east",
+		values: [1, 0],
+		metadata: {
+			kind: "axis",
+			rank: 1
+		}
+	},
+	{
+		id: "north",
+		values: [0, 1],
+		metadata: {
+			kind: "axis",
+			rank: 2
+		}
+	},
+	{
+		id: "north-east",
+		values: [1, 1],
+		metadata: {
+			kind: "diagonal",
+			rank: 3
+		}
+	},
+	{
+		id: "west",
+		values: [-1, 0],
+		metadata: {
+			kind: "axis",
+			rank: 4,
+			lonely: true
+		}
+	}
+];
+const vectorContract = [
+	{
+		name: "a Vector upserted is fetched back with its values and metadata, in the order asked, leaving out ids it does not hold",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 3,
+				metric: "cosine"
+			});
+			const docs = vectorDb(engine).namespace("docs");
+			equal(await docs.upsert([{
+				id: "a",
+				values: [
+					.5,
+					.25,
+					1
+				],
+				metadata: {
+					lang: "en",
+					year: 2026,
+					draft: false
+				}
+			}, {
+				id: "b",
+				values: [
+					1,
+					2,
+					3
+				]
+			}]), { upserted: 2 }, "the upsert's answer");
+			equal(await docs.fetch([
+				"b",
+				"missing",
+				"a"
+			]), [{
+				id: "b",
+				values: [
+					1,
+					2,
+					3
+				]
+			}, {
+				id: "a",
+				values: [
+					.5,
+					.25,
+					1
+				],
+				metadata: {
+					lang: "en",
+					year: 2026,
+					draft: false
+				}
+			}], "the fetch");
+			equal(await docs.describe(), {
+				dimension: 3,
+				metric: "cosine",
+				count: 2
+			}, "the namespace");
+		}
+	},
+	{
+		name: "an upsert replaces a Vector with the same id whole, metadata included, and a delete removes it; deleting one not there is not an error",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 2,
+				metric: "dot"
+			});
+			const docs = vectorDb(engine).namespace("docs");
+			await docs.upsert([{
+				id: "a",
+				values: [1, 2],
+				metadata: { lang: "en" }
+			}]);
+			await docs.upsert([{
+				id: "a",
+				values: [3, 4]
+			}]);
+			equal(await docs.fetch(["a"]), [{
+				id: "a",
+				values: [3, 4]
+			}], "the replaced Vector");
+			await docs.delete(["a", "never-there"]);
+			equal(await docs.fetch(["a"]), [], "the fetch after its delete");
+			equal((await docs.describe()).count, 0, "the count after its delete");
+		}
+	},
+	{
+		name: "a cosine query answers the topK closest by cosine similarity, highest first, without values or metadata unless asked",
+		async run(engine) {
+			await engine.create("compass", {
+				dimension: 2,
+				metric: "cosine"
+			});
+			const compass = vectorDb(engine).namespace("compass");
+			await compass.upsert(points);
+			const matches = await compass.query([2, 0], { topK: 3 });
+			equal(matches.map((m) => m.id), [
+				"east",
+				"north-east",
+				"north"
+			], "the ids, closest first");
+			near(matches.map((m) => m.score), [
+				1,
+				Math.SQRT1_2,
+				0
+			], "the scores");
+			equal(matches.map((m) => [m.values, m.metadata]), [
+				[void 0, void 0],
+				[void 0, void 0],
+				[void 0, void 0]
+			], "values and metadata left out");
+			equal((await compass.query([2, 0], {
+				topK: 1,
+				includeValues: true,
+				includeMetadata: true
+			})).map(({ score: _, ...rest }) => rest), [{
+				id: "east",
+				values: [1, 0],
+				metadata: {
+					kind: "axis",
+					rank: 1
+				}
+			}], "a match with values and metadata");
+		}
+	},
+	{
+		name: "a euclidean query answers distances, lowest first, and a dot query answers dot products, highest first",
+		async run(engine) {
+			await engine.create("flat", {
+				dimension: 2,
+				metric: "euclidean"
+			});
+			await engine.create("dots", {
+				dimension: 2,
+				metric: "dot"
+			});
+			const flat = vectorDb(engine).namespace("flat");
+			const dots = vectorDb(engine).namespace("dots");
+			await flat.upsert(points);
+			await dots.upsert(points);
+			const near1 = await flat.query([1, 0], { topK: 4 });
+			equal(near1.map((m) => m.id), [
+				"east",
+				"north-east",
+				"north",
+				"west"
+			], "euclidean order");
+			near(near1.map((m) => m.score), [
+				0,
+				1,
+				Math.SQRT2,
+				2
+			], "euclidean distances");
+			const dot = await dots.query([3, 1], { topK: 4 });
+			equal(dot.map((m) => m.id), [
+				"north-east",
+				"east",
+				"north",
+				"west"
+			], "dot order");
+			near(dot.map((m) => m.score), [
+				4,
+				3,
+				1,
+				-3
+			], "dot products");
+		}
+	},
+	{
+		name: "equal scores come in id order, and topK cuts the matches",
+		async run(engine) {
+			await engine.create("ties", {
+				dimension: 2,
+				metric: "dot"
+			});
+			const ties = vectorDb(engine).namespace("ties");
+			await ties.upsert([
+				{
+					id: "c",
+					values: [1, 0]
+				},
+				{
+					id: "a",
+					values: [1, 0]
+				},
+				{
+					id: "b",
+					values: [1, 0]
+				},
+				{
+					id: "d",
+					values: [0, 1]
+				}
+			]);
+			equal((await ties.query([1, 0], { topK: 2 })).map((m) => m.id), ["a", "b"], "the first two of three ties");
+			equal((await ties.query([1, 0])).map((m) => m.id), [
+				"a",
+				"b",
+				"c",
+				"d"
+			], "every Vector, under the default topK of 10");
+		}
+	},
+	{
+		name: "a filter keeps only Vectors whose metadata meets every condition; a missing field meets only $ne and $nin",
+		async run(engine) {
+			await engine.create("compass", {
+				dimension: 2,
+				metric: "dot"
+			});
+			const compass = vectorDb(engine).namespace("compass");
+			await compass.upsert(points);
+			const ids = async (filter) => (await compass.query([0, 0], {
+				topK: 10,
+				filter
+			})).map((m) => m.id).sort();
+			equal(await ids({ kind: "axis" }), [
+				"east",
+				"north",
+				"west"
+			], "a bare value");
+			equal(await ids({ kind: { $ne: "axis" } }), ["north-east"], "$ne");
+			equal(await ids({ rank: { $in: [1, 3] } }), ["east", "north-east"], "$in");
+			equal(await ids({ rank: { $nin: [1, 3] } }), ["north", "west"], "$nin");
+			equal(await ids({ rank: {
+				$gt: 1,
+				$lte: 3
+			} }), ["north", "north-east"], "a range");
+			equal(await ids({
+				kind: "axis",
+				rank: { $gte: 2 }
+			}), ["north", "west"], "two fields");
+			equal(await ids({ lonely: true }), ["west"], "a boolean");
+			equal(await ids({ lonely: { $ne: true } }), [
+				"east",
+				"north",
+				"north-east"
+			], "$ne on a field some lack");
+			equal(await ids({ lonely: { $nin: [true] } }), [
+				"east",
+				"north",
+				"north-east"
+			], "$nin on a field some lack");
+			equal(await ids({ rank: { $gt: "1" } }), [], "a string bound never orders a number");
+		}
+	},
+	{
+		name: "a Vector or query of another dimension is invalid, and a refused upsert keeps none of its Vectors",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 3,
+				metric: "euclidean"
+			});
+			const docs = vectorDb(engine).namespace("docs");
+			await fails(docs.upsert([{
+				id: "a",
+				values: [
+					1,
+					2,
+					3
+				]
+			}, {
+				id: "b",
+				values: [1, 2]
+			}]), "invalid", "an upsert with a short Vector");
+			equal(await docs.fetch(["a", "b"]), [], "nothing kept from it");
+			await fails(docs.query([
+				1,
+				2,
+				3,
+				4
+			]), "invalid", "a long query");
+		}
+	},
+	{
+		name: "with cosine, a Vector or query of all zeros is invalid",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 2,
+				metric: "cosine"
+			});
+			const docs = vectorDb(engine).namespace("docs");
+			await fails(docs.upsert([{
+				id: "zero",
+				values: [0, 0]
+			}]), "invalid", "a zero Vector");
+			await fails(docs.query([0, 0]), "invalid", "a zero query");
+		}
+	},
+	{
+		name: "a namespace that does not exist is not_found for every call",
+		async run(engine) {
+			const nowhere = vectorDb(engine).namespace("nowhere");
+			await fails(nowhere.describe(), "not_found", "describe");
+			await fails(nowhere.upsert([{
+				id: "a",
+				values: [1]
+			}]), "not_found", "upsert");
+			await fails(nowhere.query([1]), "not_found", "query");
+			await fails(nowhere.fetch(["a"]), "not_found", "fetch");
+			await fails(nowhere.delete(["a"]), "not_found", "delete");
+		}
+	},
+	{
+		name: "a namespace's dimension and metric are fixed: making it again the same way changes nothing, another way is a conflict",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 2,
+				metric: "cosine"
+			});
+			await vectorDb(engine).namespace("docs").upsert([{
+				id: "a",
+				values: [1, 0]
+			}]);
+			await engine.create("docs", {
+				dimension: 2,
+				metric: "cosine"
+			});
+			equal(await vectorDb(engine).namespace("docs").describe(), {
+				dimension: 2,
+				metric: "cosine",
+				count: 1
+			}, "the namespace made again");
+			await fails(engine.create("docs", {
+				dimension: 3,
+				metric: "cosine"
+			}), "conflict", "another dimension");
+			await fails(engine.create("docs", {
+				dimension: 2,
+				metric: "dot"
+			}), "conflict", "another metric");
+		}
+	},
+	{
+		name: "namespaces are apart: a Vector in one is not in another, and dropping one leaves the other",
+		async run(engine) {
+			await engine.create("one", {
+				dimension: 1,
+				metric: "dot"
+			});
+			await engine.create("two", {
+				dimension: 1,
+				metric: "dot"
+			});
+			const db = vectorDb(engine);
+			await db.namespace("one").upsert([{
+				id: "a",
+				values: [1]
+			}]);
+			equal(await db.namespace("two").fetch(["a"]), [], "the other namespace");
+			await engine.drop("one");
+			await engine.drop("one");
+			await fails(db.namespace("one").describe(), "not_found", "the dropped namespace");
+			equal((await db.namespace("two").describe()).count, 0, "the namespace left");
+		}
+	},
+	{
+		name: "what a caller does to the arrays it upserted or was answered does not change what is stored",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 2,
+				metric: "dot"
+			});
+			const docs = vectorDb(engine).namespace("docs");
+			const values = [1, 2];
+			const metadata = { lang: "en" };
+			await docs.upsert([{
+				id: "a",
+				values,
+				metadata
+			}]);
+			values[0] = 9;
+			metadata.lang = "fr";
+			const [fetched] = await docs.fetch(["a"]);
+			fetched.values[1] = 9;
+			equal(await docs.fetch(["a"]), [{
+				id: "a",
+				values: [1, 2],
+				metadata: { lang: "en" }
+			}], "the stored Vector");
+		}
+	},
+	{
+		name: "names, ids, values, filters and limits are checked before a call reaches the engine",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 1,
+				metric: "dot"
+			});
+			const db = vectorDb(engine);
+			const docs = db.namespace("docs");
+			await fails(Promise.resolve().then(() => db.namespace("Docs")), "invalid", "an uppercase name");
+			await fails(docs.upsert([]), "invalid", "an empty upsert");
+			await fails(docs.upsert([{
+				id: "",
+				values: [1]
+			}]), "invalid", "an empty id");
+			await fails(docs.upsert([{
+				id: "a",
+				values: [NaN]
+			}]), "invalid", "a NaN value");
+			await fails(docs.upsert([{
+				id: "a",
+				values: [1]
+			}, {
+				id: "a",
+				values: [2]
+			}]), "invalid", "one id twice");
+			await fails(docs.upsert([{
+				id: "a",
+				values: [1],
+				metadata: { $kind: "x" }
+			}]), "invalid", "a field starting with $");
+			await fails(docs.upsert([{
+				id: "a",
+				values: [1],
+				metadata: { "a.b": "x" }
+			}]), "invalid", "a field holding a dot");
+			await fails(docs.query([1], { topK: 0 }), "invalid", "topK 0");
+			await fails(docs.query([1], { topK: 101 }), "invalid", "topK 101");
+			await fails(docs.query([1], { filter: { kind: { $like: "x" } } }), "invalid", "an unknown operator");
+			await fails(docs.query([1], { consistency: "sometimes" }), "invalid", "an unknown consistency");
+			await fails(docs.fetch([]), "invalid", "a fetch of no ids");
+		}
+	},
+	{
+		name: "every score is a finite number, for values as large or as small as a Vector may hold",
+		async run(engine) {
+			await engine.create("angles", {
+				dimension: 2,
+				metric: "cosine"
+			});
+			await engine.create("far", {
+				dimension: 2,
+				metric: "euclidean"
+			});
+			await engine.create("dots", {
+				dimension: 2,
+				metric: "dot"
+			});
+			const db = vectorDb(engine);
+			const angles = db.namespace("angles");
+			await angles.upsert([
+				{
+					id: "big",
+					values: [0x16345785d8a0000, 0]
+				},
+				{
+					id: "tiny",
+					values: [1e-17, 0]
+				},
+				{
+					id: "both",
+					values: [0x16345785d8a0000, 0x16345785d8a0000]
+				}
+			]);
+			for (const vector of [[0x16345785d8a0000, 0], [1e-17, 0]]) {
+				const matches = await angles.query(vector);
+				equal(matches.map((m) => m.id), [
+					"big",
+					"tiny",
+					"both"
+				], `the order for ${vector[0]}`);
+				near(matches.map((m) => m.score), [
+					1,
+					1,
+					Math.SQRT1_2
+				], `cosine scores for ${vector[0]}`);
+			}
+			const far = db.namespace("far");
+			await far.upsert([{
+				id: "corner",
+				values: [0x16345785d8a0000, -0x16345785d8a0000]
+			}, {
+				id: "origin",
+				values: [0, 0]
+			}]);
+			const distances = await far.query([-0x16345785d8a0000, 0x16345785d8a0000]);
+			equal(distances.map((m) => m.id), ["origin", "corner"], "the euclidean order");
+			near(distances.map((m) => m.score), [0x16345785d8a0000 * Math.SQRT2, 0x2c68af0bb140000 * Math.SQRT2], "euclidean distances");
+			const dots = db.namespace("dots");
+			await dots.upsert([{
+				id: "big",
+				values: [0x16345785d8a0000, 0x16345785d8a0000]
+			}]);
+			near((await dots.query([0x16345785d8a0000, 0x16345785d8a0000])).map((m) => m.score), [2e34], "the dot product of the largest values");
+		}
+	},
+	{
+		name: "a namespace made with an embedding model takes text: the Vector of a query's own text is found first, kept as values, not text",
+		async run(engine) {
+			await engine.create("notes", {
+				dimension: 1024,
+				metric: "cosine",
+				embed: "bge-m3"
+			});
+			const notes = vectorDb(engine).namespace("notes");
+			const texts = {
+				cat: "The cat sat on the warm mat by the door",
+				revenue: "Quarterly revenue grew by four percent in Europe",
+				reset: "How to reset a forgotten account password"
+			};
+			equal(await notes.upsert(Object.entries(texts).map(([id, text]) => ({
+				id,
+				text,
+				metadata: { text }
+			}))), { upserted: 3 }, "the upsert's answer");
+			const [best] = await notes.query(texts.reset, {
+				topK: 3,
+				includeMetadata: true
+			});
+			equal([best?.id, best?.metadata], ["reset", { text: texts.reset }], "the closest Vector");
+			if (!(best.score > .99)) throw new Error(`the score of a query's own text: expected about 1, got ${best.score}`);
+			const [kept] = await notes.fetch(["cat"]);
+			equal([Object.keys(kept), kept.values.length], [[
+				"id",
+				"values",
+				"metadata"
+			], 1024], "the stored Vector");
+			await fails(engine.create("notes", {
+				dimension: 1024,
+				metric: "cosine"
+			}), "conflict", "making it again without its embedding model");
+		}
+	},
+	{
+		name: "a namespace made without an embedding model refuses text as invalid",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 2,
+				metric: "cosine"
+			});
+			const docs = vectorDb(engine).namespace("docs");
+			await fails(docs.upsert([{
+				id: "a",
+				text: "hello"
+			}]), "invalid", "an upsert of text");
+			await fails(docs.query("hello"), "invalid", "a query by text");
+			await fails(docs.upsert([{
+				id: "a",
+				text: "   "
+			}]), "invalid", "an upsert of all spaces");
+			equal((await docs.describe()).count, 0, "the count after refused upserts");
+		}
+	},
+	{
+		name: "a value beyond 1e17 in size is invalid",
+		async run(engine) {
+			await engine.create("docs", {
+				dimension: 1,
+				metric: "dot"
+			});
+			const docs = vectorDb(engine).namespace("docs");
+			await fails(docs.upsert([{
+				id: "a",
+				values: [0x163457ab195e400]
+			}]), "invalid", "an upsert just past 1e17");
+			await fails(docs.upsert([{
+				id: "a",
+				values: [1e39]
+			}]), "invalid", "an upsert of 1e39");
+			await fails(docs.query([-1e39]), "invalid", "a query of -1e39");
+		}
+	}
+];
+function equal(actual, expected, what) {
+	const a = JSON.stringify(actual);
+	const e = JSON.stringify(expected);
+	if (a !== e) throw new Error(`${what}: expected ${e}, got ${a}`);
+}
+/** Each score a finite number within a millionth of what was expected, relative to its size once past 1. */
+function near(actual, expected, what) {
+	const off = (value, index) => !Number.isFinite(value) || Math.abs(value - expected[index]) > 1e-6 * Math.max(1, Math.abs(expected[index]));
+	if (actual.length !== expected.length || actual.some(off)) throw new Error(`${what}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+async function fails(call, code, what) {
+	try {
+		await call;
+	} catch (error) {
+		if (error instanceof VectorError && error.code === code) return;
+		throw new Error(`${what}: expected ${code}, got ${error instanceof VectorError ? error.code : String(error)}`);
+	}
+	throw new Error(`${what}: expected ${code}, but it succeeded`);
+}
+//#endregion
+export { vectorContract };

package/vector/index.d.mts

@@ -0,0 +1,2 @@
+import { C as MAX_TOP_K, D as vectorErrorCodes, E as VectorErrorCode, S as MAX_TEXT, T as VectorError, _ as embedded, a as Match, b as MAX_DIMENSION, c as Namespace, d as TextVector, f as ValuesEngine, g as VectorEngine, h as VectorDb, i as Filter, l as NamespaceInfo, m as VectorControl, n as Consistency, o as MetadataValue, p as Vector, r as EngineQuery, s as Metric, t as Condition, u as QueryOptions, v as vectorDb, w as MAX_VALUE, x as MAX_METADATA_BYTES, y as MAX_BATCH } from "../index-DdoK0y7D.mjs";
+export { Condition, Consistency, EngineQuery, Filter, MAX_BATCH, MAX_DIMENSION, MAX_METADATA_BYTES, MAX_TEXT, MAX_TOP_K, MAX_VALUE, Match, MetadataValue, Metric, Namespace, NamespaceInfo, QueryOptions, TextVector, ValuesEngine, Vector, VectorControl, VectorDb, VectorEngine, VectorError, type VectorErrorCode, embedded, vectorDb, vectorErrorCodes };