@remit/search-service 0.0.18 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/search-service",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/embeddings.ts

@@ -203,3 +203,52 @@ export class LocalEmbeddingService implements EmbeddingService {
 export const createLocalEmbeddingService = (
 	config?: LocalEmbeddingConfig,
 ): EmbeddingService => new LocalEmbeddingService(config);
+
+/**
+ * Semantic search is off on this instance (`SEARCH_EMBEDDING_PROVIDER=off`).
+ *
+ * It carries the same `code` a missing model raises, because it is the same
+ * capability absence from every caller's point of view: the backend's semantic
+ * paths classify it through `noteSemanticCapabilityAbsence` and take the route
+ * they already have for a deployment that cannot embed
+ * (packages/backend/src/service/semantic-capability.ts). Returning empty
+ * results from the embedder instead would report an unavailable pipeline as a
+ * search that found nothing.
+ */
+export class EmbeddingDisabledError extends Error {
+	readonly code = "ERR_EMBEDDING_MODEL_UNAVAILABLE";
+	constructor() {
+		super(
+			"Semantic search is off on this instance (SEARCH_EMBEDDING_PROVIDER=off)",
+		);
+		this.name = "EmbeddingDisabledError";
+	}
+}
+
+/**
+ * The embedder for `SEARCH_EMBEDDING_PROVIDER=off`: nothing is embedded, and
+ * the first caller that asks gets the typed absence above.
+ *
+ * It still reports a dimension count, because the vector store's column is
+ * created from it (`buildVectorStoreFromEnv`) and the stored vectors outlive
+ * the setting — turning semantic search off keeps `vec.db` as it is, and
+ * turning it back on must find the same 384-wide column rather than a store
+ * that disagrees with the embedder.
+ */
+export class DisabledEmbeddingService implements EmbeddingService {
+	readonly dimensions: number;
+	readonly embeddingId: string;
+
+	constructor(dimensions: number = DEFAULT_LOCAL_DIMENSIONS) {
+		this.dimensions = dimensions;
+		this.embeddingId = `off@${this.dimensions}`;
+	}
+
+	embed = async (): Promise<number[][]> => {
+		throw new EmbeddingDisabledError();
+	};
+}
+
+export const createDisabledEmbeddingService = (
+	dimensions?: number,
+): EmbeddingService => new DisabledEmbeddingService(dimensions);

package/src/from-env.test.ts

@@ -1,6 +1,10 @@
 import assert from "node:assert/strict";
 import { afterEach, describe, it } from "node:test";
-import { buildEmbeddingServiceFromEnv } from "./from-env.js";
+import { EmbeddingDisabledError } from "./embeddings.js";
+import {
+	buildEmbeddingServiceFromEnv,
+	readEmbeddingProviderFromEnv,
+} from "./from-env.js";
 
 const ENV_KEYS = [
 	"SEARCH_EMBEDDING_PROVIDER",
@@ -60,3 +64,70 @@ describe("buildEmbeddingServiceFromEnv dtype handling", () => {
 		assert.equal(service.embeddingId, "deterministic@64");
 	});
 });
+
+describe("SEARCH_EMBEDDING_PROVIDER=off", () => {
+	it("builds an embedder that embeds nothing", () => {
+		process.env.SEARCH_EMBEDDING_PROVIDER = "off";
+		delete process.env.SEARCH_EMBEDDING_DIMENSIONS;
+
+		const service = buildEmbeddingServiceFromEnv();
+
+		assert.equal(service.embeddingId, "off@384");
+	});
+
+	it("keeps the store's column width, so turning it back on finds the vectors it left", () => {
+		process.env.SEARCH_EMBEDDING_PROVIDER = "off";
+
+		assert.equal(buildEmbeddingServiceFromEnv().dimensions, 384);
+	});
+
+	it("raises the capability absence the backend already degrades on, not empty results", async () => {
+		process.env.SEARCH_EMBEDDING_PROVIDER = "off";
+		const service = buildEmbeddingServiceFromEnv();
+
+		await assert.rejects(
+			() => service.embed(["anything"]),
+			(error: unknown) => {
+				assert.ok(error instanceof EmbeddingDisabledError);
+				assert.equal(
+					(error as { code: string }).code,
+					"ERR_EMBEDDING_MODEL_UNAVAILABLE",
+				);
+				return true;
+			},
+		);
+	});
+});
+
+describe("readEmbeddingProviderFromEnv", () => {
+	it("accepts every provider this deployment understands", () => {
+		for (const provider of ["off", "local", "bedrock", "deterministic"]) {
+			process.env.SEARCH_EMBEDDING_PROVIDER = provider;
+			assert.equal(readEmbeddingProviderFromEnv(), provider);
+		}
+	});
+
+	it("falls back to the deterministic embedder when nothing is set", () => {
+		delete process.env.SEARCH_EMBEDDING_PROVIDER;
+		assert.equal(readEmbeddingProviderFromEnv(), "deterministic");
+
+		process.env.SEARCH_EMBEDDING_PROVIDER = "";
+		assert.equal(readEmbeddingProviderFromEnv(), "deterministic");
+	});
+
+	it("rejects a value nothing selects, rather than indexing with the test embedder", () => {
+		for (const garbage of ["Off", "none", "disabled", "loca", "true"]) {
+			process.env.SEARCH_EMBEDDING_PROVIDER = garbage;
+			assert.throws(
+				() => readEmbeddingProviderFromEnv(),
+				/SEARCH_EMBEDDING_PROVIDER must be one of/,
+				garbage,
+			);
+			assert.throws(
+				() => buildEmbeddingServiceFromEnv(),
+				/SEARCH_EMBEDDING_PROVIDER must be one of/,
+				garbage,
+			);
+		}
+	});
+});

package/src/from-env.ts

@@ -6,10 +6,52 @@ import { createS3VectorsBackend } from "./backends/s3-vectors.js";
 import { createSqliteVectorStore } from "./backends/sqlite-vec.js";
 import {
 	createDeterministicEmbeddingService,
+	createDisabledEmbeddingService,
 	createLocalEmbeddingService,
 	type EmbeddingService,
 } from "./embeddings.js";
 
+/**
+ * The embedding providers this deployment understands.
+ *
+ * `off` is a first-class value, not an absent one: the self-host stack ships
+ * with semantic search off (deploy/vps/remit.env.template), and an operator
+ * turns it on with `remit semantic on`. `deterministic` is the unit-test and
+ * e2e embedder, named here so an environment can ask for it rather than
+ * getting it by falling through.
+ *
+ * Anything else fails the process at startup. A typo used to select the
+ * deterministic embedder, which writes real-looking vectors nothing can match
+ * a query against — a silently useless index on a box that reported success.
+ */
+const PROVIDERS = ["off", "local", "bedrock", "deterministic"] as const;
+
+export type EmbeddingProvider = (typeof PROVIDERS)[number];
+
+/** The provider when `SEARCH_EMBEDDING_PROVIDER` is unset: unit tests and the shims. */
+const DEFAULT_PROVIDER: EmbeddingProvider = "deterministic";
+
+export const EMBEDDING_PROVIDER_OFF: EmbeddingProvider = "off";
+
+const isProvider = (value: string): value is EmbeddingProvider =>
+	(PROVIDERS as readonly string[]).includes(value);
+
+/**
+ * `SEARCH_EMBEDDING_PROVIDER`, validated. Shared with the search-index worker,
+ * which gates its own memory governor and its startup on the same value, so the
+ * vocabulary and the rejection live in one place.
+ */
+export const readEmbeddingProviderFromEnv = (): EmbeddingProvider => {
+	const raw = process.env.SEARCH_EMBEDDING_PROVIDER;
+	if (raw === undefined || raw === "") return DEFAULT_PROVIDER;
+	if (!isProvider(raw)) {
+		throw new Error(
+			`SEARCH_EMBEDDING_PROVIDER must be one of ${PROVIDERS.join(", ")}, got: ${raw}`,
+		);
+	}
+	return raw;
+};
+
 const parseDimensions = (): number | undefined => {
 	const raw = process.env.SEARCH_EMBEDDING_DIMENSIONS;
 	if (!raw) return undefined;
@@ -86,12 +128,19 @@ export const buildVectorStoreFromEnv = (
 /**
  * Select an embedder from the environment, mirroring `buildVectorStoreFromEnv`:
  *
+ * - `SEARCH_EMBEDDING_PROVIDER=off` → nothing embeds. The self-host default: the
+ *   search-index worker sits behind the `semantic` compose profile and is not
+ *   running, and the backend's semantic paths take their existing unavailable
+ *   route (packages/backend/src/service/semantic-capability.ts) rather than
+ *   reporting an unavailable pipeline as a search that found nothing. FTS5 text
+ *   search is unaffected.
  * - `SEARCH_EMBEDDING_PROVIDER=local` → Transformers.js model (local dev). The
  *   model is `SEARCH_EMBEDDING_MODEL_ID` (default MiniLM); the self-host stack
  *   points it at a multilingual MiniLM so the ~50% non-English mail corpus
  *   embeds well. Both models are 384-dim, so the vector column is stable.
  * - `SEARCH_EMBEDDING_PROVIDER=bedrock` → Bedrock Titan (prod).
- * - otherwise → deterministic bag-of-words embedder (unit tests / default).
+ * - `SEARCH_EMBEDDING_PROVIDER=deterministic`, or unset → deterministic
+ *   bag-of-words embedder (unit tests / default). Any other value fails here.
  *
  * `SEARCH_EMBEDDING_DIMENSIONS`, when set, pins the dimension count for the local
  * and deterministic embedders so the store's vector column and the embedder
@@ -102,8 +151,11 @@ export const buildVectorStoreFromEnv = (
  * `fp32`. The search-index-worker container sets `q8` and bakes the matching file.
  */
 export const buildEmbeddingServiceFromEnv = (): EmbeddingService => {
-	const provider = process.env.SEARCH_EMBEDDING_PROVIDER;
+	const provider = readEmbeddingProviderFromEnv();
 	const dimensions = parseDimensions();
+	if (provider === "off") {
+		return createDisabledEmbeddingService(dimensions);
+	}
 	if (provider === "local") {
 		return createLocalEmbeddingService({
 			modelId: process.env.SEARCH_EMBEDDING_MODEL_ID,

package/src/index.ts

@@ -33,9 +33,12 @@ export {
 export { computeContentHash } from "./content-hash.js";
 export {
 	createDeterministicEmbeddingService,
+	createDisabledEmbeddingService,
 	createLocalEmbeddingService,
 	type DeterministicEmbeddingConfig,
 	DeterministicEmbeddingService,
+	DisabledEmbeddingService,
+	EmbeddingDisabledError,
 	EmbeddingModelUnavailableError,
 	type EmbeddingService,
 	type LocalEmbeddingConfig,