@remit/search-service 0.0.8 → 0.0.10

package/package.json

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

package/src/backends/sqlite-vec.integ.test.ts

@@ -142,3 +142,58 @@ describe("sqlite-vec store (integration)", { skip: !RUN }, () => {
 		assert.equal(hashes.size, 0);
 	});
 });
+
+/**
+ * The SQLITE_VEC_EXTENSION_PATH override branch — how the Alpine/musl backend
+ * image loads its own vec0.so instead of the npm package's glibc prebuilt. This
+ * suite runs on the glibc dev host, so it points the override at the npm
+ * package's own resolved loadable path: it proves the loader short-circuits
+ * getLoadablePath() and loads the extension via db.loadExtension(path), then
+ * drives the same vec0 read path (create table, upsert, cosine KNN) through it.
+ * The musl build of that .so is asserted to dlopen at image-build time in the
+ * Dockerfile's sqlite-vec-musl stage.
+ */
+describe("sqlite-vec store — SQLITE_VEC_EXTENSION_PATH override (integration)", {
+	skip: !RUN,
+}, () => {
+	let store: VectorStoreService;
+	let previous: string | undefined;
+
+	before(async () => {
+		previous = process.env.SQLITE_VEC_EXTENSION_PATH;
+		const { getLoadablePath } = await import("sqlite-vec");
+		process.env.SQLITE_VEC_EXTENSION_PATH = getLoadablePath();
+		store = createSqliteVectorStore({
+			path: ":memory:",
+			dimensions: DIMENSIONS,
+		});
+	});
+
+	after(async () => {
+		await store.close?.();
+		if (previous === undefined) {
+			delete process.env.SQLITE_VEC_EXTENSION_PATH;
+		} else {
+			process.env.SQLITE_VEC_EXTENSION_PATH = previous;
+		}
+	});
+
+	test("loads the extension from the override path and ranks by cosine", async () => {
+		await store.upsert([
+			record("o-x", [1, 0, 0, 0], { messageId: "m-ox", contentHash: "hx" }),
+			record("o-z", [0.9, 0.1, 0, 0], {
+				messageId: "m-oz",
+				contentHash: "hz",
+			}),
+			record("o-y", [0, 1, 0, 0], { messageId: "m-oy", contentHash: "hy" }),
+		]);
+
+		const matches = await store.query({ vector: [1, 0, 0, 0], topK: 3 });
+
+		assert.deepEqual(
+			matches.map((m) => m.chunkId),
+			["o-x", "o-z", "o-y"],
+		);
+		assert.ok(matches[0].score > 0.99);
+	});
+});

package/src/backends/sqlite-vec.ts

@@ -21,6 +21,24 @@ type SqliteVecModule = {
 	load: (db: Database) => void;
 };
 
+// `SQLITE_VEC_EXTENSION_PATH` overrides the npm `sqlite-vec` package's
+// getLoadablePath() with a pre-built loadable extension. That package resolves a
+// glibc-only prebuilt (`sqlite-vec-<platform>/vec0.so`) which cannot dlopen on
+// the Alpine/musl backend image, so that image bakes a musl-compiled `vec0.so`
+// and points this at it. better-sqlite3 derives the entry point from the
+// filename, and the `vec0` basename resolves to `sqlite3_vec_init` (SQLite drops
+// the digit). Unset keeps the npm resolution — the glibc search-index-worker
+// image sets nothing and loads the package unchanged.
+const loadSqliteVec = async (db: Database): Promise<void> => {
+	const overridePath = process.env.SQLITE_VEC_EXTENSION_PATH;
+	if (overridePath) {
+		db.loadExtension(overridePath);
+		return;
+	}
+	const sqliteVec = await runtimeImport<SqliteVecModule>("sqlite-vec");
+	sqliteVec.load(db);
+};
+
 /**
  * vec0 stores each chunk's vector alongside the scalar fields the query path
  * filters on, so equality / range filters are pushed into the KNN instead of
@@ -127,13 +145,12 @@ export const createSqliteVectorStore = (
 		dbPromise = (async () => {
 			const { default: Database } =
 				await runtimeImport<BetterSqlite3Module>("better-sqlite3");
-			const sqliteVec = await runtimeImport<SqliteVecModule>("sqlite-vec");
 			if (config.path !== ":memory:") {
 				mkdirSync(dirname(config.path), { recursive: true });
 			}
 			const db = new Database(config.path);
 			db.pragma("journal_mode = WAL");
-			sqliteVec.load(db);
+			await loadSqliteVec(db);
 			db.exec(CREATE_TABLE(dimensions));
 			return db;
 		})();

package/src/embeddings.test.ts

@@ -1,6 +1,24 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { LocalEmbeddingService } from "./embeddings.js";
+import type { pipeline as PipelineFn } from "@huggingface/transformers";
+import {
+	EmbeddingModelUnavailableError,
+	LocalEmbeddingService,
+} from "./embeddings.js";
+
+// Exercises the model-load path without the network: the pipeline factory
+// rejects the way a failed `from_pretrained` (HuggingFace fetch failed) does.
+class FailingLoadService extends LocalEmbeddingService {
+	importCount = 0;
+	protected importTransformers(): Promise<{ pipeline: typeof PipelineFn }> {
+		this.importCount++;
+		const pipeline = (() =>
+			Promise.reject(
+				new TypeError("fetch failed"),
+			)) as unknown as typeof PipelineFn;
+		return Promise.resolve({ pipeline });
+	}
+}
 
 describe("LocalEmbeddingService", () => {
 	it("keeps the historical embeddingId when dtype is unset", () => {
@@ -25,4 +43,26 @@ describe("LocalEmbeddingService", () => {
 			"local:Xenova/paraphrase-multilingual-MiniLM-L12-v2:q8@384",
 		);
 	});
+
+	it("raises a typed EmbeddingModelUnavailableError when the model cannot be loaded", async () => {
+		const service = new FailingLoadService({ dimensions: 8 });
+		await assert.rejects(
+			() => service.embed(["hello"]),
+			(error: unknown) => {
+				assert.ok(error instanceof EmbeddingModelUnavailableError);
+				assert.equal(
+					(error as { code?: string }).code,
+					"ERR_EMBEDDING_MODEL_UNAVAILABLE",
+				);
+				return true;
+			},
+		);
+	});
+
+	it("clears the memoized pipeline on a load failure so a later call retries", async () => {
+		const service = new FailingLoadService({ dimensions: 8 });
+		await assert.rejects(() => service.embed(["hello"]));
+		await assert.rejects(() => service.embed(["hello"]));
+		assert.equal(service.importCount, 2);
+	});
 });

package/src/embeddings.ts

@@ -91,6 +91,24 @@ export interface LocalEmbeddingConfig {
 const DEFAULT_LOCAL_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
 const DEFAULT_LOCAL_DIMENSIONS = 384;
 
+/**
+ * The local embedder could not load its model. Raised when Transformers.js fails
+ * to resolve the model files — the common cause is `from_pretrained` lazily
+ * fetching the weights from HuggingFace and the network fetch failing
+ * (`TypeError: fetch failed`), which otherwise surfaces as an opaque 500.
+ *
+ * The `code` is the contract consumers match on (mirroring Node's own error
+ * codes) to degrade the semantic path to empty results instead of crashing,
+ * without importing this class or string-matching undici internals.
+ */
+export class EmbeddingModelUnavailableError extends Error {
+	readonly code = "ERR_EMBEDDING_MODEL_UNAVAILABLE";
+	constructor(modelId: string, options?: { cause?: unknown }) {
+		super(`Embedding model "${modelId}" could not be loaded`, options);
+		this.name = "EmbeddingModelUnavailableError";
+	}
+}
+
 type TransformersModule = { pipeline: typeof PipelineFn };
 
 /**
@@ -122,15 +140,34 @@ export class LocalEmbeddingService implements EmbeddingService {
 
 	private getPipeline = async (): Promise<FeatureExtractionPipeline> => {
 		if (this.pipelinePromise) return this.pipelinePromise;
-		this.pipelinePromise = (async () => {
-			const { pipeline } = await runtimeImport<TransformersModule>(
-				"@huggingface/transformers",
-			);
-			return pipeline("feature-extraction", this.modelId, {
+		const promise = this.loadPipeline();
+		this.pipelinePromise = promise;
+		try {
+			return await promise;
+		} catch (error) {
+			// A failed load (module absent, or the model could not be fetched) must
+			// not poison the instance: clear the memo so a later call retries rather
+			// than returning the same rejected promise for the process lifetime.
+			if (this.pipelinePromise === promise) this.pipelinePromise = null;
+			throw error;
+		}
+	};
+
+	// Import boundary kept overridable so a load failure can be exercised without
+	// the network; the default resolves Transformers.js lazily via runtimeImport.
+	protected importTransformers(): Promise<TransformersModule> {
+		return runtimeImport<TransformersModule>("@huggingface/transformers");
+	}
+
+	private loadPipeline = async (): Promise<FeatureExtractionPipeline> => {
+		const { pipeline } = await this.importTransformers();
+		try {
+			return await pipeline("feature-extraction", this.modelId, {
 				dtype: this.dtype,
 			});
-		})();
-		return this.pipelinePromise;
+		} catch (error) {
+			throw new EmbeddingModelUnavailableError(this.modelId, { cause: error });
+		}
 	};
 
 	embed = async (texts: string[]): Promise<number[][]> => {

package/src/index.ts

@@ -36,6 +36,7 @@ export {
 	createLocalEmbeddingService,
 	type DeterministicEmbeddingConfig,
 	DeterministicEmbeddingService,
+	EmbeddingModelUnavailableError,
 	type EmbeddingService,
 	type LocalEmbeddingConfig,
 	LocalEmbeddingService,