@forwardimpact/svcembedding 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Zachary Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -0,0 +1,54 @@
+import { services } from "@forwardimpact/librpc";
+
+const { EmbeddingBase } = services;
+
+/**
+ * gRPC service that produces text embeddings by delegating to a
+ * Text Embeddings Inference (TEI) HTTP backend over its OpenAI-compatible
+ * `/v1/embeddings` endpoint. The TEI process is spawned by `server.js`; this
+ * class is a thin adapter that translates the proto request/response shapes
+ * to and from TEI's HTTP payload.
+ *
+ * Implements the `Embedding.CreateEmbeddings` RPC defined in
+ * `proto/embedding.proto`; see `generated/services/embedding/service.js` for
+ * the `EmbeddingBase` it extends.
+ */
+export class EmbeddingService extends EmbeddingBase {
+  #backendUrl;
+
+  /**
+   * @param {import("@forwardimpact/libconfig").ServiceConfig} config -
+   *   Service configuration from `createServiceConfig("embedding")`.
+   * @param {string} backendUrl - Base URL of the TEI HTTP backend
+   *   (e.g. `http://127.0.0.1:8090`), without a trailing slash. Required;
+   *   construction throws if empty.
+   */
+  constructor(config, backendUrl) {
+    super(config);
+    if (!backendUrl) throw new Error("backendUrl is required");
+    this.#backendUrl = backendUrl;
+  }
+
+  /**
+   * Embed one or more input strings via the TEI backend.
+   *
+   * @param {{input: string[]}} req - Proto-decoded `EmbeddingsRequest`.
+   *   `input` is the list of text strings to embed; order is preserved in
+   *   the response.
+   * @returns {Promise<{data: Array<{values: number[]}>}>} A proto-shaped
+   *   `EmbeddingsResponse` with one `EmbeddingVector` per input, in the same
+   *   order. `values` is the dense embedding from the configured TEI model.
+   * @throws {Error} If the TEI backend returns a non-2xx status. The error
+   *   message includes the HTTP status code.
+   */
+  async CreateEmbeddings(req) {
+    const res = await fetch(`${this.#backendUrl}/v1/embeddings`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ input: req.input, model: "default" }),
+    });
+    if (!res.ok) throw new Error(`TEI request failed: ${res.status}`);
+    const body = await res.json();
+    return { data: body.data.map((d) => ({ values: d.embedding })) };
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@forwardimpact/svcembedding",
+  "version": "0.1.1",
+  "description": "Text embeddings over gRPC — semantic representation without each product running its own inference.",
+  "keywords": [
+    "embedding",
+    "vector",
+    "inference",
+    "grpc",
+    "agent"
+  ],
+  "homepage": "https://www.forwardimpact.team",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forwardimpact/monorepo.git",
+    "directory": "services/embedding"
+  },
+  "license": "Apache-2.0",
+  "author": "D. Olsson <hi@senzilla.io>",
+  "jobs": [
+    {
+      "user": "Platform Builders",
+      "goal": "Ground Agents in Context",
+      "trigger": "An agent needs to answer relationship questions, search by meaning, or read activity data, and the only alternative is direct database access and per-product plumbing.",
+      "bigHire": "give agents graph queries, semantic search, embeddings, and activity data through shared services that never leak schema or credentials.",
+      "littleHire": "call one gRPC method instead of wiring HTTP, auth, and retries per product.",
+      "competesWith": "direct database access from agents; per-product retrieval endpoints; inline fetch calls; external search infrastructure; skipping semantic search entirely"
+    }
+  ],
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "fit-svcembedding": "./server.js"
+  },
+  "files": [
+    "proto/",
+    "server.js"
+  ],
+  "scripts": {
+    "dev": "node --watch server.js",
+    "start": "bun server.js",
+    "test": "bun test test/*.test.js"
+  },
+  "dependencies": {
+    "@forwardimpact/libcli": "^0.1.14",
+    "@forwardimpact/libconfig": "^0.1.58",
+    "@forwardimpact/libpreflight": "^0.1.0",
+    "@forwardimpact/librpc": "^0.1.77",
+    "@forwardimpact/libtelemetry": "^0.1.41",
+    "@forwardimpact/libutil": "^0.1.85"
+  },
+  "devDependencies": {
+    "@forwardimpact/libmock": "^0.1.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/proto/embedding.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package embedding;
+
+service Embedding {
+  rpc CreateEmbeddings(EmbeddingsRequest) returns (EmbeddingsResponse);
+}
+
+message EmbeddingsRequest {
+  // Text strings to embed
+  repeated string input = 1;
+}
+
+message EmbeddingVector {
+  // Embedding values for a single input
+  repeated float values = 1;
+}
+
+message EmbeddingsResponse {
+  // One vector per input string, in order
+  repeated EmbeddingVector data = 1;
+}

package/server.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import "@forwardimpact/libpreflight/node22";
+
+import { serverFlagsShortCircuit } from "@forwardimpact/libcli/server-flags";
+import { spawn } from "node:child_process";
+import { Server } from "@forwardimpact/librpc";
+import { createServiceConfig } from "@forwardimpact/libconfig";
+import { createTracer } from "@forwardimpact/librpc";
+import { createLogger } from "@forwardimpact/libtelemetry";
+import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
+
+import { EmbeddingService } from "./index.js";
+
+const handled = serverFlagsShortCircuit({
+  name: "fit-svcembedding",
+  description: "Text embeddings gRPC service",
+  packageJsonUrl: new URL("./package.json", import.meta.url),
+  argv: process.argv.slice(2),
+});
+
+if (!handled) {
+  const config = await createServiceConfig("embedding", {
+    port: 3015,
+    backend_port: 8090,
+    model: "BAAI/bge-small-en-v1.5",
+  });
+
+  const runtime = createDefaultRuntime();
+  const logger = createLogger("embedding", runtime);
+  const tracer = await createTracer("embedding");
+
+  const backend_port = config.backend_port;
+  const model = config.model;
+  const backendUrl = `http://127.0.0.1:${backend_port}`;
+
+  const tei = spawn(
+    "text-embeddings-router",
+    ["--model-id", model, "--port", String(backend_port), "--json-output"],
+    { stdio: "inherit" },
+  );
+
+  for (const sig of ["SIGTERM", "SIGINT"]) {
+    process.on(sig, () => {
+      tei.kill(sig);
+    });
+  }
+
+  tei.on("exit", (code, signal) => {
+    process.exit(signal ? 1 : (code ?? 1));
+  });
+
+  const service = new EmbeddingService(config, backendUrl);
+  const server = new Server(service, config, { logger, tracer, runtime });
+
+  await server.start();
+}