@crewhaus/embedder 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/embedder",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Embedding provider — openai/voyage/cohere/local/mock backends with prefix-grammar selector",
   "main": "src/index.ts",
@@ -12,13 +12,13 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.1"
+    "@crewhaus/errors": "0.1.3"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -30,12 +30,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test";
 import { EmbedderError, createEmbedder, parseEmbedderModel } from "./index";
 
 describe("parseEmbedderModel", () => {
@@ -147,3 +147,356 @@ describe("Section 30 — embedder magnitude snapshots", () => {
     expect(() => createEmbedder({ model: "cohere/embed-v3" })).toThrow();
   });
 });
+
+// ---------------------------------------------------------------------------
+// createEmbedder — provider branch coverage (env + explicit key).
+// ---------------------------------------------------------------------------
+
+/** Save/restore a single env var around a callback. */
+function withEnv(key: string, value: string | undefined, fn: () => void): void {
+  const original = process.env[key];
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+  try {
+    fn();
+  } finally {
+    if (original === undefined) delete process.env[key];
+    else process.env[key] = original;
+  }
+}
+
+describe("createEmbedder — provider construction branches", () => {
+  test("openai reads OPENAI_API_KEY from env when no explicit key", () => {
+    withEnv("OPENAI_API_KEY", "sk-env", () => {
+      const e = createEmbedder({ model: "openai/text-embedding-3-small" });
+      expect(e.provider).toBe("openai");
+      expect(e.model).toBe("text-embedding-3-small");
+    });
+  });
+
+  test("openai accepts an explicit apiKey override", () => {
+    withEnv("OPENAI_API_KEY", undefined, () => {
+      const e = createEmbedder({ model: "openai/text-embedding-3-small", apiKey: "sk-explicit" });
+      expect(e.provider).toBe("openai");
+    });
+  });
+
+  test("voyage reads VOYAGE_API_KEY from env", () => {
+    withEnv("VOYAGE_API_KEY", "voyage-env", () => {
+      const e = createEmbedder({ model: "voyage/voyage-3" });
+      expect(e.provider).toBe("voyage");
+    });
+  });
+
+  test("voyage throws fail-loud when VOYAGE_API_KEY is empty", () => {
+    withEnv("VOYAGE_API_KEY", "", () => {
+      expect(() => createEmbedder({ model: "voyage/voyage-3" })).toThrow(/VOYAGE_API_KEY/);
+    });
+  });
+
+  test("cohere reads COHERE_API_KEY from env", () => {
+    withEnv("COHERE_API_KEY", "cohere-env", () => {
+      const e = createEmbedder({ model: "cohere/embed-v3" });
+      expect(e.provider).toBe("cohere");
+    });
+  });
+
+  test("cohere throws fail-loud when COHERE_API_KEY is empty", () => {
+    withEnv("COHERE_API_KEY", "", () => {
+      expect(() => createEmbedder({ model: "cohere/embed-v3" })).toThrow(/COHERE_API_KEY/);
+    });
+  });
+
+  test("local/ honors an explicit baseUrl override over the parsed one", () => {
+    const e = createEmbedder({
+      model: "local/x@http://parsed:1234",
+      baseUrl: "http://override:5678",
+    });
+    expect(e.provider).toBe("local");
+    expect(e.model).toBe("x");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// OpenAILikeEmbedder.embed — network path (fetch mocked, fully deterministic).
+// ---------------------------------------------------------------------------
+
+describe("OpenAILikeEmbedder.embed (mocked fetch)", () => {
+  afterEach(() => {
+    // spyOn(globalThis, "fetch") registers with bun's mock registry; restore
+    // the real implementation after every test so nothing leaks across files.
+    mock.restore();
+  });
+
+  test("empty input short-circuits without a network call", async () => {
+    const fetchSpy = spyOn(globalThis, "fetch");
+    const e = createEmbedder({ model: "openai/text-embedding-3-small", apiKey: "sk-x" });
+    expect(await e.embed([])).toEqual([]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  test("posts to /v1/embeddings with an Authorization header and parses data", async () => {
+    let capturedUrl = "";
+    let capturedInit: RequestInit | undefined;
+    const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+      capturedUrl = String(input);
+      capturedInit = init;
+      return new Response(JSON.stringify({ data: [{ embedding: [0.1, 0.2, 0.3] }] }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+    const fetchSpy = spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "openai/text-embedding-3-small", apiKey: "sk-secret" });
+    const out = await e.embed(["hello"]);
+
+    expect(out).toEqual([[0.1, 0.2, 0.3]]);
+    expect(capturedUrl).toBe("https://api.openai.com/v1/embeddings");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const headers = capturedInit?.headers as Record<string, string>;
+    expect(headers["authorization"]).toBe("Bearer sk-secret");
+    expect(headers["content-type"]).toBe("application/json");
+    const body = JSON.parse(String(capturedInit?.body)) as { model: string; input: string[] };
+    expect(body.model).toBe("text-embedding-3-small");
+    expect(body.input).toEqual(["hello"]);
+    // No signal provided → fetch init must not carry one.
+    expect(capturedInit?.signal ?? null).toBeNull();
+  });
+
+  test("local provider without an API key omits the Authorization header", async () => {
+    let capturedInit: RequestInit | undefined;
+    const fetchImpl = (async (_input: string | URL | Request, init?: RequestInit) => {
+      capturedInit = init;
+      return new Response(JSON.stringify({ data: [{ embedding: [1, 0] }] }), { status: 200 });
+    }) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "local/nomic@http://localhost:11434" });
+    const out = await e.embed(["x"]);
+
+    expect(out).toEqual([[1, 0]]);
+    const headers = capturedInit?.headers as Record<string, string>;
+    expect("authorization" in headers).toBe(false);
+  });
+
+  test("respects a custom batchSize and concatenates batches in order", async () => {
+    const batches: string[][] = [];
+    const fetchImpl = (async (_input: string | URL | Request, init?: RequestInit) => {
+      const parsed = JSON.parse(String(init?.body)) as { input: string[] };
+      batches.push(parsed.input);
+      // Echo one embedding per input text so we can verify ordering.
+      const data = parsed.input.map((t) => ({ embedding: [t.length] }));
+      return new Response(JSON.stringify({ data }), { status: 200 });
+    }) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "local/m@http://localhost:1234" });
+    const out = await e.embed(["a", "bb", "ccc", "dddd", "eeeee"], { batchSize: 2 });
+
+    // 5 texts / batchSize 2 → batches of [2, 2, 1].
+    expect(batches).toEqual([["a", "bb"], ["ccc", "dddd"], ["eeeee"]]);
+    expect(out).toEqual([[1], [2], [3], [4], [5]]);
+  });
+
+  test("forwards an AbortSignal to fetch", async () => {
+    let capturedSignal: AbortSignal | null | undefined;
+    const fetchImpl = (async (_input: string | URL | Request, init?: RequestInit) => {
+      capturedSignal = init?.signal;
+      return new Response(JSON.stringify({ data: [{ embedding: [0] }] }), { status: 200 });
+    }) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const controller = new AbortController();
+    const e = createEmbedder({ model: "local/m@http://localhost:1234" });
+    await e.embed(["x"], { signal: controller.signal });
+    expect(capturedSignal).toBe(controller.signal);
+  });
+
+  test("throws EmbedderError with status + body on a non-ok response", async () => {
+    const fetchImpl = (async () =>
+      new Response("rate limited", {
+        status: 429,
+        statusText: "Too Many Requests",
+      })) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "openai/text-embedding-3-small", apiKey: "sk-x" });
+    await expect(e.embed(["x"])).rejects.toThrow(EmbedderError);
+    await expect(e.embed(["x"])).rejects.toThrow(/429 rate limited/);
+  });
+
+  test("non-ok response with an unreadable body still throws (text() rejects)", async () => {
+    // A Response whose .text() rejects exercises the `.catch(() => "")` arm.
+    const brokenResponse = {
+      ok: false,
+      status: 500,
+      text: () => Promise.reject(new Error("stream broken")),
+    } as unknown as Response;
+    const fetchImpl = (async () => brokenResponse) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "openai/text-embedding-3-small", apiKey: "sk-x" });
+    // Body coerces to empty string → message ends at the status, no trailing text.
+    await expect(e.embed(["x"])).rejects.toThrow(/500 $/);
+  });
+
+  test("a baseUrl already carrying /v1 is not doubled (URL-shape tolerance)", async () => {
+    let capturedUrl = "";
+    const fetchImpl = (async (input: string | URL | Request) => {
+      capturedUrl = String(input);
+      return new Response(JSON.stringify({ data: [{ embedding: [1] }] }), { status: 200 });
+    }) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "local/nomic@http://localhost:11434/v1" });
+    await e.embed(["x"]);
+    expect(capturedUrl).toBe("http://localhost:11434/v1/embeddings");
+  });
+
+  test("a baseUrl with a trailing slash + /v1/ also normalises", async () => {
+    let capturedUrl = "";
+    const fetchImpl = (async (input: string | URL | Request) => {
+      capturedUrl = String(input);
+      return new Response(JSON.stringify({ data: [{ embedding: [1] }] }), { status: 200 });
+    }) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "local/nomic@http://localhost:11434/v1/" });
+    await e.embed(["x"]);
+    expect(capturedUrl).toBe("http://localhost:11434/v1/embeddings");
+  });
+
+  test("cohere defaults to the /compatibility OpenAI-compat endpoint (bare host 404s)", async () => {
+    let capturedUrl = "";
+    const fetchImpl = (async (input: string | URL | Request) => {
+      capturedUrl = String(input);
+      return new Response(JSON.stringify({ data: [{ embedding: [0.5] }] }), { status: 200 });
+    }) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "cohere/embed-v4.0", apiKey: "co-x" });
+    const out = await e.embed(["x"]);
+    expect(out).toEqual([[0.5]]);
+    expect(capturedUrl).toBe("https://api.cohere.ai/compatibility/v1/embeddings");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gemini backend — REST embedContent (fetch mocked, fully deterministic).
+// ---------------------------------------------------------------------------
+
+describe("gemini embedder (mocked fetch)", () => {
+  afterEach(() => {
+    mock.restore();
+  });
+
+  test("parses gemini/<model>", () => {
+    expect(parseEmbedderModel("gemini/gemini-embedding-001")).toEqual({
+      providerId: "gemini",
+      modelId: "gemini-embedding-001",
+    });
+  });
+
+  test("requires GEMINI_API_KEY or GOOGLE_API_KEY", () => {
+    const prevGemini = process.env["GEMINI_API_KEY"];
+    const prevGoogle = process.env["GOOGLE_API_KEY"];
+    process.env["GEMINI_API_KEY"] = "";
+    process.env["GOOGLE_API_KEY"] = "";
+    try {
+      expect(() => createEmbedder({ model: "gemini/gemini-embedding-001" })).toThrow(
+        /GEMINI_API_KEY/,
+      );
+    } finally {
+      process.env["GEMINI_API_KEY"] = prevGemini;
+      process.env["GOOGLE_API_KEY"] = prevGoogle;
+    }
+  });
+
+  test("falls back to GOOGLE_API_KEY when GEMINI_API_KEY is unset", () => {
+    const prevGemini = process.env["GEMINI_API_KEY"];
+    const prevGoogle = process.env["GOOGLE_API_KEY"];
+    process.env["GEMINI_API_KEY"] = "";
+    process.env["GOOGLE_API_KEY"] = "g-key";
+    try {
+      const e = createEmbedder({ model: "gemini/gemini-embedding-001" });
+      expect(e.provider).toBe("gemini");
+    } finally {
+      process.env["GEMINI_API_KEY"] = prevGemini;
+      process.env["GOOGLE_API_KEY"] = prevGoogle;
+    }
+  });
+
+  test("POSTs models/<model>:embedContent with key query param + {content:{parts:[{text}]}} body and reads embedding.values", async () => {
+    const calls: Array<{ url: string; body: unknown }> = [];
+    const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(input), body: JSON.parse(String(init?.body)) });
+      return new Response(JSON.stringify({ embedding: { values: [0.1, 0.2] } }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "gemini/gemini-embedding-001", apiKey: "g-secret" });
+    const out = await e.embed(["alpha", "beta"]);
+
+    // One request per text (the endpoint takes a single content body).
+    expect(calls.length).toBe(2);
+    expect(out).toEqual([
+      [0.1, 0.2],
+      [0.1, 0.2],
+    ]);
+    expect(calls[0]?.url).toBe(
+      "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=g-secret",
+    );
+    expect(calls[0]?.body).toEqual({ content: { parts: [{ text: "alpha" }] } });
+    expect(calls[1]?.body).toEqual({ content: { parts: [{ text: "beta" }] } });
+  });
+
+  test("empty input short-circuits without a network call", async () => {
+    const fetchSpy = spyOn(globalThis, "fetch");
+    const e = createEmbedder({ model: "gemini/gemini-embedding-001", apiKey: "g-x" });
+    expect(await e.embed([])).toEqual([]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  test("throws EmbedderError on a non-ok response", async () => {
+    const fetchImpl = (async () =>
+      new Response("permission denied", { status: 403 })) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "gemini/gemini-embedding-001", apiKey: "g-x" });
+    await expect(e.embed(["x"])).rejects.toThrow(EmbedderError);
+    await expect(e.embed(["x"])).rejects.toThrow(/403 permission denied/);
+  });
+
+  test("throws EmbedderError when the response carries no embedding.values", async () => {
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({ embedding: {} }), { status: 200 })) as unknown as typeof fetch;
+    spyOn(globalThis, "fetch").mockImplementation(fetchImpl);
+
+    const e = createEmbedder({ model: "gemini/gemini-embedding-001", apiKey: "g-x" });
+    await expect(e.embed(["x"])).rejects.toThrow(/embedding\.values/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// hashedBow — zero-norm branch (no alphanumeric tokens → all-zero vector).
+// ---------------------------------------------------------------------------
+
+describe("mock embedder — zero vector edge case", () => {
+  test("punctuation/whitespace-only text yields an all-zero, non-normalised vector", async () => {
+    const e = createEmbedder({ model: "mock/det" });
+    const [vec] = await e.embed(["   !!! ??? ---   "]);
+    expect(vec?.length).toBe(256);
+    // norm === 0 → returns the raw zero vector unchanged (no divide-by-zero).
+    expect(vec?.every((x) => x === 0)).toBe(true);
+  });
+
+  test("empty string also yields an all-zero vector", async () => {
+    const e = createEmbedder({ model: "mock/det" });
+    const [vec] = await e.embed([""]);
+    expect(vec?.every((x) => x === 0)).toBe(true);
+  });
+});

package/src/index.ts

@@ -5,7 +5,8 @@
  *
  *   openai/text-embedding-3-small    → OpenAI Embeddings API
  *   voyage/voyage-3                  → Voyage AI
- *   cohere/embed-v3                  → Cohere
+ *   cohere/embed-v3                  → Cohere (OpenAI-compat endpoint)
+ *   gemini/gemini-embedding-001      → Google Generative Language REST API
  *   local/<model>@<base-url>         → OpenAI-compatible local server
  *   mock/deterministic               → in-process hashed BoW vectors (tests + smoke fallback)
  *
@@ -23,7 +24,7 @@
 import { createHash } from "node:crypto";
 import { CrewhausError } from "@crewhaus/errors";
 
-export type EmbedderProviderId = "openai" | "voyage" | "cohere" | "local" | "mock";
+export type EmbedderProviderId = "openai" | "voyage" | "cohere" | "gemini" | "local" | "mock";
 
 export type ParsedEmbedderModel = {
   readonly providerId: EmbedderProviderId;
@@ -44,6 +45,7 @@ export class EmbedderError extends CrewhausError {
  *   openai/text-embedding-3-small
  *   voyage/voyage-3
  *   cohere/embed-v3
+ *   gemini/gemini-embedding-001
  *   local/<model>@<base-url>
  *   mock/<anything>
  */
@@ -60,6 +62,9 @@ export function parseEmbedderModel(spec: string): ParsedEmbedderModel {
   if (spec.startsWith("cohere/")) {
     return { providerId: "cohere", modelId: spec.slice("cohere/".length) };
   }
+  if (spec.startsWith("gemini/")) {
+    return { providerId: "gemini", modelId: spec.slice("gemini/".length) };
+  }
   if (spec.startsWith("local/")) {
     const rest = spec.slice("local/".length);
     const at = rest.lastIndexOf("@");
@@ -74,7 +79,7 @@ export function parseEmbedderModel(spec: string): ParsedEmbedderModel {
     return { providerId: "mock", modelId: spec.slice("mock/".length) };
   }
   throw new EmbedderError(
-    `unknown embedder prefix in "${spec}" — expected openai/, voyage/, cohere/, local/<m>@<url>, or mock/`,
+    `unknown embedder prefix in "${spec}" — expected openai/, voyage/, cohere/, gemini/, local/<m>@<url>, or mock/`,
   );
 }
 
@@ -133,15 +138,30 @@ class MockEmbedder implements Embedder {
 // servers like Ollama, vLLM, llama.cpp).
 // ---------------------------------------------------------------------------
 
+/**
+ * Normalise a baseUrl before appending `/v1/embeddings`: strip a trailing
+ * slash AND a trailing `/v1` segment so both URL shapes users commonly
+ * supply work (`http://localhost:11434` and `http://localhost:11434/v1`
+ * both resolve to `.../v1/embeddings` — never `.../v1/v1/embeddings`).
+ */
+function normaliseEmbeddingsBaseUrl(baseUrl: string): string {
+  let out = baseUrl;
+  if (out.endsWith("/")) out = out.slice(0, -1);
+  if (out.endsWith("/v1")) out = out.slice(0, -"/v1".length);
+  return out;
+}
+
 class OpenAILikeEmbedder implements Embedder {
   readonly provider: EmbedderProviderId;
+  private readonly baseUrl: string;
   constructor(
     provider: EmbedderProviderId,
     public readonly model: string,
-    private readonly baseUrl: string,
+    baseUrl: string,
     private readonly apiKey: string | undefined,
   ) {
     this.provider = provider;
+    this.baseUrl = normaliseEmbeddingsBaseUrl(baseUrl);
   }
   async embed(texts: ReadonlyArray<string>, opts: EmbedOptions = {}): Promise<number[][]> {
     if (texts.length === 0) return [];
@@ -172,6 +192,53 @@ class OpenAILikeEmbedder implements Embedder {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Gemini — Google Generative Language REST API. Not OpenAI-shaped: one
+// POST per text to `models/<model>:embedContent` with the API key as a
+// query param, response carries `embedding.values`. The per-text loop is
+// fine for the embedder's batch sizes (the API has no multi-text body on
+// this endpoint shape).
+// ---------------------------------------------------------------------------
+
+const GEMINI_EMBED_BASE = "https://generativelanguage.googleapis.com/v1beta";
+
+class GeminiEmbedder implements Embedder {
+  readonly provider: EmbedderProviderId = "gemini";
+  constructor(
+    public readonly model: string,
+    private readonly apiKey: string,
+    private readonly baseUrl: string = GEMINI_EMBED_BASE,
+  ) {}
+  async embed(texts: ReadonlyArray<string>, opts: EmbedOptions = {}): Promise<number[][]> {
+    if (texts.length === 0) return [];
+    const out: number[][] = [];
+    for (const text of texts) {
+      const url = `${this.baseUrl}/models/${this.model}:embedContent?key=${encodeURIComponent(this.apiKey)}`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ content: { parts: [{ text }] } }),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new EmbedderError(
+          `embedding request failed (gemini ${this.model}): ${res.status} ${body}`,
+        );
+      }
+      const json = (await res.json()) as { embedding?: { values?: number[] } };
+      const values = json.embedding?.values;
+      if (!Array.isArray(values)) {
+        throw new EmbedderError(
+          `gemini embedding response missing embedding.values (model ${this.model})`,
+        );
+      }
+      out.push(values);
+    }
+    return out;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Factory.
 // ---------------------------------------------------------------------------
@@ -218,13 +285,29 @@ export function createEmbedder(opts: CreateEmbedderOptions): Embedder {
       if (apiKey === undefined || apiKey === "") {
         throw new EmbedderError("cohere embedder requires COHERE_API_KEY");
       }
+      // Cohere's OpenAI-compatible surface lives under /compatibility —
+      // the bare host has no /v1/embeddings path (it 404s).
       return new OpenAILikeEmbedder(
         "cohere",
         parsed.modelId,
-        opts.baseUrl ?? "https://api.cohere.ai",
+        opts.baseUrl ?? "https://api.cohere.ai/compatibility",
         apiKey,
       );
     }
+    case "gemini": {
+      // Empty-string env values count as unset so GOOGLE_API_KEY can take
+      // over when GEMINI_API_KEY="" (common in CI matrices).
+      const candidates = [
+        opts.apiKey,
+        process.env["GEMINI_API_KEY"],
+        process.env["GOOGLE_API_KEY"],
+      ];
+      const apiKey = candidates.find((k) => k !== undefined && k !== "");
+      if (apiKey === undefined) {
+        throw new EmbedderError("gemini embedder requires GEMINI_API_KEY (or GOOGLE_API_KEY)");
+      }
+      return new GeminiEmbedder(parsed.modelId, apiKey, opts.baseUrl ?? GEMINI_EMBED_BASE);
+    }
     case "local":
       return new OpenAILikeEmbedder(
         "local",