feat: implement and serve the local v1/embeddings endpoint with full …

flake.nix

@@ -25,8 +25,13 @@
         devShells.default = pkgs.mkShell {
           packages = with pkgs; [
             bun
+            gcc
             typescript-language-server
           ];
+
+          shellHook = ''
+            export LD_LIBRARY_PATH="${pkgs.stdenv.cc.cc.lib}/lib''${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+          '';
         };
       }
     );

package.json

@@ -16,6 +16,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
     "@opencode-ai/sdk": "^1.18.11",
     "zod": "^4.4.3"
   },

src/app.ts

@@ -1,15 +1,19 @@
 import { Router } from "./router.ts";
 import { chatCompletionsHandler } from "./routes/v1/chat/completions.ts";
+import { embeddingsHandler } from "./routes/v1/embeddings.ts";
 import { modelsHandler } from "./routes/v1/models.ts";
 import type { ChatCompletionsService } from "./services/chat-completions.ts";
+import type { EmbeddingsService } from "./services/embeddings.ts";
 import type { ModelsService } from "./services/models.ts";
 
 export function buildRouter(
   chatCompletions: ChatCompletionsService,
   models: ModelsService,
+  embeddings: EmbeddingsService,
 ): Router {
   const router = new Router();
   router.register("POST", "/v1/chat/completions", chatCompletionsHandler(chatCompletions));
   router.register("GET", "/v1/models", modelsHandler(models));
+  router.register("POST", "/v1/embeddings", embeddingsHandler(embeddings));
   return router;
 }

src/config.test.ts

@@ -1,7 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import { loadConfig } from "./config.ts";
 
-const DEFAULTS = { host: "127.0.0.1", port: 8000, opencodeUrl: null };
+const DEFAULTS = {
+  host: "127.0.0.1",
+  port: 8000,
+  opencodeUrl: null,
+  embeddingsModel: "Xenova/bge-small-en-v1.5",
+  embeddingsPreload: false,
+};
 
 describe("loadConfig", () => {
   test("defaults host, port, and opencode url", () => {
@@ -19,11 +25,15 @@ describe("loadConfig", () => {
         PORT: "9000",
         HOST: "0.0.0.0",
         OPENCODE_URL: "http://opencode.example:7777",
+        EMBEDDINGS_MODEL: "Xenova/all-MiniLM-L6-v2",
+        EMBEDDINGS_PRELOAD: "true",
       }),
     ).toEqual({
       host: "0.0.0.0",
       port: 9000,
       opencodeUrl: "http://opencode.example:7777",
+      embeddingsModel: "Xenova/all-MiniLM-L6-v2",
+      embeddingsPreload: true,
     });
   });
 
@@ -33,11 +43,15 @@ describe("loadConfig", () => {
         PORT: " 8123 ",
         HOST: " localhost ",
         OPENCODE_URL: " http://opencode.example:7777 ",
+        EMBEDDINGS_MODEL: " Xenova/all-MiniLM-L6-v2 ",
+        EMBEDDINGS_PRELOAD: " true ",
       }),
     ).toEqual({
       host: "localhost",
       port: 8123,
       opencodeUrl: "http://opencode.example:7777",
+      embeddingsModel: "Xenova/all-MiniLM-L6-v2",
+      embeddingsPreload: true,
     });
   });
 
@@ -62,4 +76,27 @@ describe("loadConfig", () => {
   test("throws for a non-http(s) OPENCODE_URL", () => {
     expect(() => loadConfig({ OPENCODE_URL: "ftp://example.com" })).toThrow(/invalid OPENCODE_URL/);
   });
+
+  test("reads EMBEDDINGS_PRELOAD false", () => {
+    expect(loadConfig({ EMBEDDINGS_PRELOAD: "false" }).embeddingsPreload).toBe(false);
+  });
+
+  test("throws for non-boolean EMBEDDINGS_PRELOAD values", () => {
+    for (const value of ["1", "0", "yes", "no", "on", "y", "n", " random "]) {
+      expect(() => loadConfig({ EMBEDDINGS_PRELOAD: value })).toThrow(/invalid EMBEDDINGS_PRELOAD/);
+    }
+  });
+
+  test("throws for empty or whitespace-only EMBEDDINGS_PRELOAD", () => {
+    for (const value of ["", "   ", "\t\n "]) {
+      expect(() => loadConfig({ EMBEDDINGS_PRELOAD: value })).toThrow(
+        /invalid EMBEDDINGS_PRELOAD/,
+      );
+    }
+  });
+
+  test("accepts case-insensitive EMBEDDINGS_PRELOAD booleans", () => {
+    expect(loadConfig({ EMBEDDINGS_PRELOAD: "TRUE" }).embeddingsPreload).toBe(true);
+    expect(loadConfig({ EMBEDDINGS_PRELOAD: "False" }).embeddingsPreload).toBe(false);
+  });
 });

src/config.ts

@@ -1,11 +1,16 @@
 import { parseHttpUrl } from "./utils/net.ts";
+import { parseBoolean } from "./utils/parse.ts";
 
 export interface Config {
   host: string;
   port: number;
   opencodeUrl: string | null;
+  embeddingsModel: string;
+  embeddingsPreload: boolean;
 }
 
+const DEFAULT_EMBEDDINGS_MODEL = "Xenova/bge-small-en-v1.5";
+
 export function loadConfig(env: Record<string, string | undefined> = process.env): Config {
   const port = Number(env.PORT?.trim() || 8000);
   if (!Number.isInteger(port) || port < 0 || port > 65_535) {
@@ -16,9 +21,21 @@ export function loadConfig(env: Record<string, string | undefined> = process.env
   if (opencodeUrl && !parseHttpUrl(opencodeUrl)) {
     throw new Error(`invalid OPENCODE_URL "${opencodeUrl}": expected an absolute http(s) URL`);
   }
+  const embeddingsModel = env.EMBEDDINGS_MODEL?.trim() || DEFAULT_EMBEDDINGS_MODEL;
+  const rawPreload = env.EMBEDDINGS_PRELOAD?.trim();
+  const parsedPreload = rawPreload === undefined ? false : parseBoolean(rawPreload);
+  if (parsedPreload === undefined) {
+    throw new Error(
+      `invalid EMBEDDINGS_PRELOAD "${env.EMBEDDINGS_PRELOAD}": expected "true" or "false"`,
+    );
+  }
+  const embeddingsPreload = parsedPreload;
+
   return {
     host: env.HOST?.trim() || "127.0.0.1",
     port,
     opencodeUrl,
+    embeddingsModel,
+    embeddingsPreload,
   };
 }