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

package/vector/index.mjs

@@ -0,0 +1,108 @@
+import { a as MAX_TEXT, c as NamespaceName, d as Vectors, f as checked, i as MAX_METADATA_BYTES, l as Query, m as vectorErrorCodes, n as MAX_BATCH, o as MAX_TOP_K, p as VectorError, r as MAX_DIMENSION, s as MAX_VALUE, t as Ids } from "../schema-DS8x1Dn8.mjs";
+//#region src/vector/index.ts
+/**
+* Vector DB: a Team's Vectors in Vector namespaces, searched by closeness and filtered by their
+* metadata.
+*
+* In your Deployment's server, Midsummer hands in the Environment's Vector DB as `context.vector`.
+* A namespace is named by the name the Environment binds it under (`midsummer env binding set`):
+*
+*   import { vectorDb } from "@midsummer-ai/sdk/vector"
+*   import { remote } from "@midsummer-ai/sdk/vector/wire"
+*
+*   const docs = vectorDb(remote(context.vector)).namespace("docs")
+*   await docs.upsert([{ id: "intro", values: [0.1, 0.2, 0.3], metadata: { lang: "en" } }])
+*   const matches = await docs.query([0.1, 0.2, 0.25], { topK: 5, filter: { lang: "en" }, includeMetadata: true })
+*
+*   // A namespace made with an embedding model takes text: it is embedded as it is written or asked.
+*   await notes.upsert([{ id: "reset", text: "How to reset a forgotten password", metadata: { lang: "en" } }])
+*   const [best] = await notes.query("I forgot my password", { topK: 1 })
+*   const [intro] = await docs.fetch(["intro"])
+*   await docs.delete(["intro"])
+*
+* In tests and `midsummer dev`, `standIn()` from `@midsummer-ai/sdk/vector/stand-in` keeps Vectors in
+* memory. Each is held to the cases in `@midsummer-ai/sdk/vector/contract`; a behaviour that is not a
+* case there is not promised.
+*
+* A Vector namespace is made with its dimension and metric, which never change: through the
+* platform (`midsummer vector namespace create`), or the Stand-in's `create`. Made with an embedding
+* model (`embed`), which never changes either, it takes text wherever it takes values: each text is
+* embedded by that model as part of the write or query that carries it, and its vector is stored or
+* searched. The text itself is not kept; a Vector that needs it back keeps it in its metadata. Code reads and writes
+* the Vectors of the namespaces its Environment has; it never makes or drops one.
+*
+* Calls are checked here, before anything leaves the caller. Every failure is a `VectorError`; its
+* `code` tells you which kind, and is the same code the wire carries.
+*/
+/** Vector DB over `engine`. */
+function vectorDb(engine) {
+	return { namespace(name) {
+		checked(NamespaceName, name);
+		return {
+			name,
+			async upsert(vectors) {
+				return engine.upsert(name, checked(Vectors, vectors));
+			},
+			async query(vector, options = {}) {
+				return engine.query(name, checked(Query, {
+					...typeof vector === "string" ? { text: vector } : { vector },
+					topK: options.topK ?? 10,
+					includeValues: options.includeValues ?? false,
+					includeMetadata: options.includeMetadata ?? false,
+					...options.filter !== void 0 ? { filter: options.filter } : {},
+					...options.consistency !== void 0 ? { consistency: options.consistency } : {}
+				}));
+			},
+			async fetch(ids) {
+				return engine.fetch(name, checked(Ids, ids));
+			},
+			async delete(ids) {
+				return engine.delete(name, checked(Ids, ids));
+			},
+			async describe() {
+				return engine.describe(name);
+			}
+		};
+	} };
+}
+/**
+* `engine`, which keeps only values, taking text too: the texts of each call are embedded by `embed`,
+* given the namespace and the texts in order, before `engine` sees the call. `embed` returns
+* `undefined` for a namespace made without an embedding model, which is `invalid`.
+*
+*   const site = embedded(engine, (namespace, texts) => vector.embed(namespace, texts))
+*/
+function embedded(engine, embed) {
+	async function values(namespace, texts) {
+		const found = await embed(namespace, texts);
+		if (!found) throw new VectorError("invalid", "This Vector namespace was made without an embedding model, so it takes values, not text.");
+		return found;
+	}
+	return {
+		describe: (namespace) => engine.describe(namespace),
+		async upsert(namespace, vectors) {
+			const texts = vectors.flatMap((vector) => "text" in vector ? [vector.text] : []);
+			if (!texts.length) return engine.upsert(namespace, vectors);
+			const embeddings = await values(namespace, texts);
+			let next = 0;
+			return engine.upsert(namespace, vectors.map((vector) => "text" in vector ? {
+				id: vector.id,
+				values: embeddings[next++],
+				...vector.metadata ? { metadata: vector.metadata } : {}
+			} : vector));
+		},
+		async query(namespace, query) {
+			if (!("text" in query)) return engine.query(namespace, query);
+			const { text, ...rest } = query;
+			const [vector] = await values(namespace, [text]);
+			return engine.query(namespace, {
+				...rest,
+				vector
+			});
+		},
+		fetch: (namespace, ids) => engine.fetch(namespace, ids),
+		delete: (namespace, ids) => engine.delete(namespace, ids)
+	};
+}
+//#endregion
+export { MAX_BATCH, MAX_DIMENSION, MAX_METADATA_BYTES, MAX_TEXT, MAX_TOP_K, MAX_VALUE, VectorError, embedded, vectorDb, vectorErrorCodes };

package/vector/stand-in.d.mts

@@ -0,0 +1,11 @@
+import { g as VectorEngine, m as VectorControl } from "../index-DdoK0y7D.mjs";
+//#region src/vector/stand-in.d.ts
+/**
+ * A text's Stand-in embedding of `dimension` numbers: each word (letters and digits, in lower case)
+ * adds 1 or -1 to the place its hash picks, and the whole is scaled to length 1. A text with no word
+ * counts as one word. Never all zeros.
+ */
+declare function localEmbedding(text: string, dimension: number): number[];
+declare function standIn(): VectorEngine & VectorControl;
+//#endregion
+export { localEmbedding, standIn };

package/vector/stand-in.mjs

@@ -0,0 +1,169 @@
+import { p as VectorError } from "../schema-DS8x1Dn8.mjs";
+import { embedded } from "./index.mjs";
+//#region src/vector/stand-in.ts
+/**
+* Vector DB's Stand-in: the Capability's behaviour in memory, for `midsummer dev` and tests. It holds
+* no engine code and passes the contract (`@midsummer-ai/sdk/vector/contract`) except durability and
+* scale. A query is an exact search: every Vector of the namespace is scored, so it returns what an
+* approximate engine aims for.
+*
+* A namespace made with an embedding model, whatever its name, embeds text with `localEmbedding`:
+* a hash of its words, free and the same everywhere, so a text and the words it shares are close and
+* the same text is found first. It is not a model's sense of meaning.
+*
+*   const engine = standIn()
+*   await engine.create("docs", { dimension: 3, metric: "cosine" })
+*   const docs = vectorDb(engine).namespace("docs")
+*
+* Everything is lost when the process ends.
+*/
+/**
+* A text's Stand-in embedding of `dimension` numbers: each word (letters and digits, in lower case)
+* adds 1 or -1 to the place its hash picks, and the whole is scaled to length 1. A text with no word
+* counts as one word. Never all zeros.
+*/
+function localEmbedding(text, dimension) {
+	const values = new Array(dimension).fill(0);
+	const words = text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [text];
+	for (const word of words) {
+		let hash = 2166136261;
+		for (let index = 0; index < word.length; index += 1) hash = Math.imul(hash ^ word.charCodeAt(index), 16777619);
+		values[(hash >>> 1) % dimension] += hash & 1 ? 1 : -1;
+	}
+	const length = Math.sqrt(values.reduce((sum, value) => sum + value * value, 0));
+	if (length === 0) return values.map((_, index) => index === 0 ? 1 : 0);
+	return values.map((value) => value / length);
+}
+function standIn() {
+	const engine = valuesOnly();
+	return {
+		...embedded(engine, async (name, texts) => {
+			const namespace = engine.held(name);
+			return namespace.embed === void 0 ? void 0 : texts.map((text) => localEmbedding(text, namespace.dimension));
+		}),
+		create: engine.create,
+		drop: engine.drop
+	};
+}
+/** The Stand-in over values alone, and its namespaces as they are held. */
+function valuesOnly() {
+	const namespaces = /* @__PURE__ */ new Map();
+	const held = (name) => {
+		const namespace = namespaces.get(name);
+		if (!namespace) throw new VectorError("not_found", `There is no Vector namespace named ${name}.`);
+		return namespace;
+	};
+	return {
+		held,
+		async create(name, settings) {
+			const current = namespaces.get(name);
+			if (!current) return void namespaces.set(name, {
+				...settings,
+				vectors: /* @__PURE__ */ new Map()
+			});
+			if (current.dimension !== settings.dimension || current.metric !== settings.metric || current.embed !== settings.embed) throw new VectorError("conflict", `The Vector namespace ${name} exists with dimension ${current.dimension} and metric ${current.metric}${current.embed ? `, embedded by ${current.embed}` : ""}.`);
+		},
+		async drop(name) {
+			namespaces.delete(name);
+		},
+		async describe(name) {
+			const namespace = held(name);
+			return {
+				dimension: namespace.dimension,
+				metric: namespace.metric,
+				count: namespace.vectors.size
+			};
+		},
+		async upsert(name, vectors) {
+			const namespace = held(name);
+			for (const vector of vectors) fits(namespace, vector.values, `Vector ${vector.id}`);
+			for (const vector of vectors) namespace.vectors.set(vector.id, {
+				...copy(vector),
+				values: vector.values.map((value) => Math.fround(value))
+			});
+			return { upserted: vectors.length };
+		},
+		async query(name, query) {
+			const namespace = held(name);
+			fits(namespace, query.vector, "The query's vector");
+			const scored = [];
+			for (const vector of namespace.vectors.values()) {
+				if (query.filter && !matches(query.filter, vector.metadata ?? {})) continue;
+				scored.push({
+					vector,
+					score: score(namespace.metric, query.vector, vector.values)
+				});
+			}
+			const closer = namespace.metric === "euclidean" ? (a, b) => a - b : (a, b) => b - a;
+			scored.sort((a, b) => closer(a.score, b.score) || (a.vector.id < b.vector.id ? -1 : a.vector.id > b.vector.id ? 1 : 0));
+			return scored.slice(0, query.topK).map(({ vector, score }) => ({
+				id: vector.id,
+				score,
+				...query.includeValues ? { values: [...vector.values] } : {},
+				...query.includeMetadata ? { metadata: { ...vector.metadata } } : {}
+			}));
+		},
+		async fetch(name, ids) {
+			const namespace = held(name);
+			return ids.flatMap((id) => {
+				const vector = namespace.vectors.get(id);
+				return vector ? [copy(vector)] : [];
+			});
+		},
+		async delete(name, ids) {
+			const namespace = held(name);
+			for (const id of ids) namespace.vectors.delete(id);
+		}
+	};
+}
+function copy(vector) {
+	return {
+		id: vector.id,
+		values: [...vector.values],
+		...vector.metadata ? { metadata: { ...vector.metadata } } : {}
+	};
+}
+/** Refuses `values` that are not the namespace's dimension, or, for cosine, all zero: they have no direction. */
+function fits(namespace, values, what) {
+	if (values.length !== namespace.dimension) throw new VectorError("invalid", `${what} has ${values.length} values; this Vector namespace's dimension is ${namespace.dimension}.`);
+	if (namespace.metric === "cosine" && values.every((value) => value === 0)) throw new VectorError("invalid", `${what} is all zeros, which has no direction for cosine.`);
+}
+/**
+* The metric's score, kept finite for any values a Vector may hold. Cosine is the dot product of the
+* two Vectors each scaled by its largest value first, so tiny values do not vanish when squared and
+* large ones do not overflow; euclidean scales the differences the same way.
+*/
+function score(metric, a, b) {
+	if (metric === "dot") {
+		let dot = 0;
+		for (let index = 0; index < a.length; index++) dot += a[index] * b[index];
+		return dot;
+	}
+	if (metric === "euclidean") {
+		const differences = a.map((x, index) => x - b[index]);
+		const largest = Math.max(...differences.map(Math.abs));
+		if (largest === 0) return 0;
+		return largest * Math.sqrt(differences.reduce((sum, d) => sum + (d / largest) ** 2, 0));
+	}
+	const unit = (values) => {
+		const largest = Math.max(...values.map(Math.abs));
+		const scaled = values.map((value) => value / largest);
+		const length = Math.sqrt(scaled.reduce((sum, value) => sum + value * value, 0));
+		return scaled.map((value) => value / length);
+	};
+	const x = unit(a);
+	const y = unit(b);
+	let cosine = 0;
+	for (let index = 0; index < x.length; index++) cosine += x[index] * y[index];
+	return Math.max(-1, Math.min(1, cosine));
+}
+function matches(filter, metadata) {
+	return Object.entries(filter).every(([field, condition]) => holds(condition, Object.hasOwn(metadata, field) ? metadata[field] : void 0));
+}
+function holds(condition, value) {
+	if (typeof condition !== "object") return value === condition;
+	const ordered = (bound, test) => value !== void 0 && typeof value === typeof bound && typeof value !== "boolean" && test(value < bound ? -1 : value > bound ? 1 : 0);
+	return (condition.$eq === void 0 || value === condition.$eq) && (condition.$ne === void 0 || value !== condition.$ne) && (condition.$in === void 0 || value !== void 0 && condition.$in.includes(value)) && (condition.$nin === void 0 || value === void 0 || !condition.$nin.includes(value)) && (condition.$gt === void 0 || ordered(condition.$gt, (order) => order > 0)) && (condition.$gte === void 0 || ordered(condition.$gte, (order) => order >= 0)) && (condition.$lt === void 0 || ordered(condition.$lt, (order) => order < 0)) && (condition.$lte === void 0 || ordered(condition.$lte, (order) => order <= 0));
+}
+//#endregion
+export { localEmbedding, standIn };

package/vector/wire.d.mts

@@ -0,0 +1,25 @@
+import { g as VectorEngine, m as VectorControl } from "../index-DdoK0y7D.mjs";
+//#region src/vector/wire.d.ts
+/** Carries one request frame to a server and brings back its answer frame. */
+interface Transport {
+  send(frame: Uint8Array): Promise<Uint8Array>;
+}
+/** An engine that sends each call over `transport`. A transport that fails is `unavailable`. */
+declare function remote(transport: Transport): VectorEngine & VectorControl;
+/**
+ * Serves request frames from `engine`. A frame comes from the network, so it is checked here as the
+ * client would check it; a refusal is returned as `invalid`. Making and dropping namespaces is
+ * served only by an engine that has them, else `forbidden`. A failure that is not a `VectorError`
+ * is the engine's own fault and is thrown to the transport, never returned.
+ */
+declare function serve(engine: VectorEngine & Partial<VectorControl>): (frame: Uint8Array) => Promise<Uint8Array>;
+/**
+ * `engine` as a Site of one Environment reaches it: `namespaceId` returns, for the one name a call
+ * names, the id the engine knows that Environment's Vector namespace by, so a call costs the lookup
+ * of its own namespace and never a listing of the others. A name with no id is `not_found`, as a
+ * namespace that does not exist is, so a Site learns nothing of other Environments. It cannot make
+ * or drop one.
+ */
+declare function scoped(engine: VectorEngine, namespaceId: (name: string) => Promise<string | undefined>): VectorEngine;
+//#endregion
+export { Transport, remote, scoped, serve };

package/vector/wire.mjs

@@ -0,0 +1,175 @@
+import { c as NamespaceName, d as Vectors, f as checked, l as Query, m as vectorErrorCodes, p as VectorError, t as Ids, u as Settings } from "../schema-DS8x1Dn8.mjs";
+import { z } from "zod";
+//#region src/vector/wire.ts
+/**
+* Vector DB's wire: one call is one frame, the UTF-8 JSON of `{ op, namespace, … }`, and its answer
+* is one frame, `{ ok }` or `{ error, why }` with a `VectorErrorCode`. A transport only carries
+* frames; a Site's own handle is one (`{ send }`), handed to it by the platform for its Environment.
+*
+*   const docs = vectorDb(remote(context.vector)).namespace("docs")   // a Site
+*   const answer = await serve(scoped(engine, (name) => vector.siteNamespace(repositoryId, environment, name)))(frame)   // the platform
+*
+* `scoped` is how the platform serves a Site: names mapped to the ids the engine knows them by, and
+* making or dropping a namespace refused.
+*/
+const call = z.discriminatedUnion("op", [
+	z.object({
+		op: z.literal("describe"),
+		namespace: z.string()
+	}),
+	z.object({
+		op: z.literal("upsert"),
+		namespace: z.string(),
+		vectors: z.unknown()
+	}),
+	z.object({
+		op: z.literal("query"),
+		namespace: z.string(),
+		query: z.unknown()
+	}),
+	z.object({
+		op: z.literal("fetch"),
+		namespace: z.string(),
+		ids: z.unknown()
+	}),
+	z.object({
+		op: z.literal("delete"),
+		namespace: z.string(),
+		ids: z.unknown()
+	}),
+	z.object({
+		op: z.literal("create"),
+		namespace: z.string(),
+		settings: z.unknown()
+	}),
+	z.object({
+		op: z.literal("drop"),
+		namespace: z.string()
+	})
+]);
+const answer = z.union([z.object({
+	error: z.enum(vectorErrorCodes),
+	why: z.string()
+}), z.object({ ok: z.unknown() })]);
+const encode = (value) => new TextEncoder().encode(JSON.stringify(value));
+/** An engine that sends each call over `transport`. A transport that fails is `unavailable`. */
+function remote(transport) {
+	async function ask(request) {
+		let frame;
+		try {
+			frame = await transport.send(encode(request));
+		} catch {
+			throw new VectorError("unavailable", "Vector DB could not be reached. Try again.");
+		}
+		let parsed;
+		try {
+			parsed = answer.parse(JSON.parse(new TextDecoder().decode(frame)));
+		} catch {
+			throw new VectorError("unavailable", "Vector DB answered something that is not a Vector DB frame");
+		}
+		if ("error" in parsed) throw new VectorError(parsed.error, parsed.why);
+		return parsed.ok;
+	}
+	return {
+		describe: (namespace) => ask({
+			op: "describe",
+			namespace
+		}),
+		upsert: (namespace, vectors) => ask({
+			op: "upsert",
+			namespace,
+			vectors
+		}),
+		query: (namespace, query) => ask({
+			op: "query",
+			namespace,
+			query
+		}),
+		fetch: (namespace, ids) => ask({
+			op: "fetch",
+			namespace,
+			ids
+		}),
+		delete: async (namespace, ids) => void await ask({
+			op: "delete",
+			namespace,
+			ids
+		}),
+		create: async (namespace, settings) => void await ask({
+			op: "create",
+			namespace,
+			settings
+		}),
+		drop: async (namespace) => void await ask({
+			op: "drop",
+			namespace
+		})
+	};
+}
+/**
+* Serves request frames from `engine`. A frame comes from the network, so it is checked here as the
+* client would check it; a refusal is returned as `invalid`. Making and dropping namespaces is
+* served only by an engine that has them, else `forbidden`. A failure that is not a `VectorError`
+* is the engine's own fault and is thrown to the transport, never returned.
+*/
+function serve(engine) {
+	return async (frame) => {
+		try {
+			let json;
+			try {
+				json = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(frame));
+			} catch {
+				throw new VectorError("invalid", "the request frame is not JSON");
+			}
+			const parsed = call.safeParse(json);
+			if (!parsed.success) throw new VectorError("invalid", "the request frame is not a Vector DB call");
+			const request = parsed.data;
+			const namespace = checked(NamespaceName, request.namespace);
+			return encode({ ok: await answerTo(engine, namespace, request) ?? null });
+		} catch (error) {
+			if (error instanceof VectorError) return encode({
+				error: error.code,
+				why: error.message
+			});
+			throw error;
+		}
+	};
+}
+async function answerTo(engine, namespace, request) {
+	switch (request.op) {
+		case "describe": return engine.describe(namespace);
+		case "upsert": return engine.upsert(namespace, checked(Vectors, request.vectors));
+		case "query": return engine.query(namespace, checked(Query, request.query));
+		case "fetch": return engine.fetch(namespace, checked(Ids, request.ids));
+		case "delete": return engine.delete(namespace, checked(Ids, request.ids));
+		case "create":
+			if (!engine.create) throw new VectorError("forbidden", "Vector namespaces are made through the platform");
+			return engine.create(namespace, checked(Settings, request.settings));
+		case "drop":
+			if (!engine.drop) throw new VectorError("forbidden", "Vector namespaces are dropped through the platform");
+			return engine.drop(namespace);
+	}
+}
+/**
+* `engine` as a Site of one Environment reaches it: `namespaceId` returns, for the one name a call
+* names, the id the engine knows that Environment's Vector namespace by, so a call costs the lookup
+* of its own namespace and never a listing of the others. A name with no id is `not_found`, as a
+* namespace that does not exist is, so a Site learns nothing of other Environments. It cannot make
+* or drop one.
+*/
+function scoped(engine, namespaceId) {
+	const id = async (name) => {
+		const found = await namespaceId(name);
+		if (found === void 0) throw new VectorError("not_found", `There is no Vector namespace named ${name}.`);
+		return found;
+	};
+	return {
+		describe: async (namespace) => engine.describe(await id(namespace)),
+		upsert: async (namespace, vectors) => engine.upsert(await id(namespace), vectors),
+		query: async (namespace, query) => engine.query(await id(namespace), query),
+		fetch: async (namespace, ids) => engine.fetch(await id(namespace), ids),
+		delete: async (namespace, ids) => engine.delete(await id(namespace), ids)
+	};
+}
+//#endregion
+export { remote, scoped, serve };

package/wire.d.mts

@@ -0,0 +1,54 @@
+import { m as StorageEngine } from "./index-sgdyoA2P.mjs";
+//#region src/wire.d.ts
+/** Carries one request frame to a server and brings back its answer frame. */
+interface Transport {
+  send(frame: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * The engine on the client's side of the wire. With `batch`, the calls made in the same turn travel
+ * as one batch frame (the platform's own calls do not batch; clients that issue many at once do).
+ */
+declare function remote(transport: Transport, options?: {
+  readonly batch?: boolean;
+}): StorageEngine;
+/**
+ * Whether sending `frame` a second time, after the first may have been carried out, returns the same as the
+ * first would have and stores nothing more: reads, an unconditional put, a delete, a part sent again.
+ * A conditional put, a copy (its source may have changed since), and starting, completing or aborting
+ * an upload are not: a second `ifNoneMatch` put is a `conflict`, a second completion `not_found`. A
+ * batch is when all it holds is and no call in it writes what another call reads or writes, so sending
+ * it again cannot see one call's effect in another's answer. A transport resends a frame it lost the
+ * answer to only when this allows it.
+ */
+declare function repeatable(frame: Uint8Array): boolean;
+/**
+ * The Bucket names that the calls in `frame` use, so a server can look up only those before serving it.
+ * A call it cannot read uses none: `serve` returns `invalid` for it without reaching a Bucket.
+ */
+declare function bucketsOf(frame: Uint8Array): string[];
+/**
+ * Serves request frames from `engine`. A frame comes from the network, so its header is checked
+ * here as the client would check it; a refusal is returned as `invalid`. A failure that is not a
+ * `StorageError` is the engine's own fault and is thrown to the transport, never returned.
+ */
+declare function serve(engine: StorageEngine): (frame: Uint8Array) => Promise<Uint8Array>;
+/**
+ * A transport over HTTP: each frame is one POST to `url` with the engine's bearer token, replied to
+ * by `serveHttp` on the other side. Refused credentials are `forbidden`; a server that cannot be
+ * reached, or replies with anything but a frame, is `unavailable`.
+ */
+declare function http(url: string, options: {
+  readonly token: string;
+  readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}): Transport;
+/** Answers `http` transports: a POST of one frame, with `token` as its bearer token, gets one answer frame. */
+declare function serveHttp(engine: StorageEngine, options: {
+  readonly token: string;
+}): (request: Request) => Promise<Response>;
+declare function encodeFrame(header: unknown, body?: Uint8Array): Uint8Array;
+declare function decodeFrame(frame: Uint8Array): {
+  header: unknown;
+  body: Uint8Array;
+};
+//#endregion
+export { Transport, bucketsOf, decodeFrame, encodeFrame, http, remote, repeatable, serve, serveHttp };