libsql-search 0.4.0 → 0.5.0

package/README.md

@@ -22,7 +22,7 @@ Use it when you want:
 - libSQL/Turso storage and vector search
 - Embedding providers: local `Xenova/all-MiniLM-L6-v2`, Cloudflare Workers AI
   `@cf/baai/bge-m3`, Mistral `mistral-embed`, Google Gemini
-  `text-embedding-004`, and OpenAI `text-embedding-3-small` /
+  `gemini-embedding-2`, and OpenAI `text-embedding-3-small` /
   `text-embedding-3-large`
 - npm distribution plus JSR publishing
 
@@ -99,7 +99,8 @@ Important behavior:
 - Keep dimensions aligned across table creation, indexing, and search queries.
 - `indexContent()` clears existing rows before rebuilding the index.
 - `local` is the default offline provider; Cloudflare is the recommended hosted
-  option. Cloudflare and Mistral use 1024 dimensions.
+  option. Cloudflare and Mistral use 1024 dimensions. Gemini defaults to 3072
+  dimensions and supports 128-3072.
 
 ## Core API
 

package/dist/index.cjs

@@ -8,7 +8,10 @@ const DEFAULT_DIMENSIONS = 768;
 const DEFAULT_MAX_LENGTH = 8e3;
 const DEFAULT_TIMEOUT_MS = 3e4;
 const LOCAL_MODEL = "Xenova/all-MiniLM-L6-v2";
-const GEMINI_MODEL = "text-embedding-004";
+const GEMINI_MODEL = "gemini-embedding-2";
+const GEMINI_DIMENSIONS = 3072;
+const GEMINI_MIN_DIMENSIONS = 128;
+const GEMINI_MAX_DIMENSIONS = 3072;
 const OPENAI_SMALL_MODEL = "text-embedding-3-small";
 const OPENAI_LARGE_MODEL = "text-embedding-3-large";
 const OPENAI_EMBEDDINGS_URL = "https://api.openai.com/v1/embeddings";
@@ -121,6 +124,22 @@ function getSafeResponseHeader(response, name) {
 function createCloudflareEmbeddingsUrl(accountId) {
   return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/v1/embeddings`;
 }
+function formatGeminiEmbeddingContent(text, intent) {
+  return intent === "query" ? `task: search result | query: ${text}` : `title: none | text: ${text}`;
+}
+function parseGeminiEmbeddingResult(result) {
+  if (!Array.isArray(result.embeddings)) {
+    throw new Error("Gemini response did not include an embeddings array");
+  }
+  if (result.embeddings.length !== 1) {
+    throw new Error(`Gemini response included ${result.embeddings.length} embedding result(s) for one input`);
+  }
+  const values = result.embeddings[0]?.values;
+  if (!Array.isArray(values)) {
+    throw new Error("Gemini response did not include embedding values");
+  }
+  return values;
+}
 async function withTimeout(provider, operation, timeoutMs, run, parentSignal, exactSecrets = []) {
   if (parentSignal?.aborted) {
     throw providerError(provider, `${operation} was aborted`);
@@ -239,7 +258,7 @@ function createProviderMetadata(provider, dimensions) {
       return Object.freeze({
         name: "gemini",
         model: GEMINI_MODEL,
-        dimensions: DEFAULT_DIMENSIONS,
+        dimensions,
         batch: Object.freeze({ mode: "sequential" })
       });
     case "openai":
@@ -267,7 +286,14 @@ function createProviderMetadata(provider, dimensions) {
 }
 function getEffectiveDimensions(provider, dimensions) {
   if (provider === "gemini") {
-    return DEFAULT_DIMENSIONS;
+    const effectiveDimensions = dimensions ?? GEMINI_DIMENSIONS;
+    if (!Number.isInteger(effectiveDimensions) || effectiveDimensions < GEMINI_MIN_DIMENSIONS || effectiveDimensions > GEMINI_MAX_DIMENSIONS) {
+      throw providerError(
+        "gemini",
+        `${GEMINI_MODEL} supports dimensions from ${GEMINI_MIN_DIMENSIONS} to ${GEMINI_MAX_DIMENSIONS}; received dimensions ${String(dimensions)}`
+      );
+    }
+    return effectiveDimensions;
   }
   if (provider === "mistral") {
     if (dimensions !== void 0 && dimensions !== MISTRAL_DIMENSIONS) {
@@ -363,16 +389,18 @@ class GeminiEmbeddingProvider {
       "API request",
       this.#timeoutMs,
       async (signal) => {
-        const { GoogleGenerativeAI } = await import('@google/generative-ai');
-        const genAI = new GoogleGenerativeAI(this.#apiKey);
-        const model = genAI.getGenerativeModel({ model: this.metadata.model });
+        const { GoogleGenAI } = await import('@google/genai');
+        const client = new GoogleGenAI({ apiKey: this.#apiKey });
         return embedSequentially("gemini", "API request", texts, signal, async (text, itemSignal) => {
-          const result = await model.embedContent(text, { signal: itemSignal });
-          const values = result.embedding?.values;
-          if (!Array.isArray(values)) {
-            throw new Error("Gemini response did not include embedding values");
-          }
-          return values;
+          const result = await client.models.embedContent({
+            model: this.metadata.model,
+            contents: formatGeminiEmbeddingContent(text, intent),
+            config: {
+              outputDimensionality: this.metadata.dimensions,
+              abortSignal: itemSignal
+            }
+          });
+          return parseGeminiEmbeddingResult(result);
         });
       },
       options.signal,
@@ -583,7 +611,9 @@ function createEmbeddingProvider(options = {}) {
     case "local":
       return new LocalEmbeddingProvider(metadata, timeoutMs);
     case "gemini": {
-      const key = options.apiKey || getEnvironmentVariable("GEMINI_API_KEY");
+      const key = getOptionalTrimmedCredential(
+        options.apiKey ?? getEnvironmentVariable("GEMINI_API_KEY")
+      );
       if (!key) {
         throw new Error("GEMINI_API_KEY is required for Gemini embeddings");
       }

package/dist/index.esm.js

@@ -6,7 +6,10 @@ const DEFAULT_DIMENSIONS = 768;
 const DEFAULT_MAX_LENGTH = 8e3;
 const DEFAULT_TIMEOUT_MS = 3e4;
 const LOCAL_MODEL = "Xenova/all-MiniLM-L6-v2";
-const GEMINI_MODEL = "text-embedding-004";
+const GEMINI_MODEL = "gemini-embedding-2";
+const GEMINI_DIMENSIONS = 3072;
+const GEMINI_MIN_DIMENSIONS = 128;
+const GEMINI_MAX_DIMENSIONS = 3072;
 const OPENAI_SMALL_MODEL = "text-embedding-3-small";
 const OPENAI_LARGE_MODEL = "text-embedding-3-large";
 const OPENAI_EMBEDDINGS_URL = "https://api.openai.com/v1/embeddings";
@@ -119,6 +122,22 @@ function getSafeResponseHeader(response, name) {
 function createCloudflareEmbeddingsUrl(accountId) {
   return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/v1/embeddings`;
 }
+function formatGeminiEmbeddingContent(text, intent) {
+  return intent === "query" ? `task: search result | query: ${text}` : `title: none | text: ${text}`;
+}
+function parseGeminiEmbeddingResult(result) {
+  if (!Array.isArray(result.embeddings)) {
+    throw new Error("Gemini response did not include an embeddings array");
+  }
+  if (result.embeddings.length !== 1) {
+    throw new Error(`Gemini response included ${result.embeddings.length} embedding result(s) for one input`);
+  }
+  const values = result.embeddings[0]?.values;
+  if (!Array.isArray(values)) {
+    throw new Error("Gemini response did not include embedding values");
+  }
+  return values;
+}
 async function withTimeout(provider, operation, timeoutMs, run, parentSignal, exactSecrets = []) {
   if (parentSignal?.aborted) {
     throw providerError(provider, `${operation} was aborted`);
@@ -237,7 +256,7 @@ function createProviderMetadata(provider, dimensions) {
       return Object.freeze({
         name: "gemini",
         model: GEMINI_MODEL,
-        dimensions: DEFAULT_DIMENSIONS,
+        dimensions,
         batch: Object.freeze({ mode: "sequential" })
       });
     case "openai":
@@ -265,7 +284,14 @@ function createProviderMetadata(provider, dimensions) {
 }
 function getEffectiveDimensions(provider, dimensions) {
   if (provider === "gemini") {
-    return DEFAULT_DIMENSIONS;
+    const effectiveDimensions = dimensions ?? GEMINI_DIMENSIONS;
+    if (!Number.isInteger(effectiveDimensions) || effectiveDimensions < GEMINI_MIN_DIMENSIONS || effectiveDimensions > GEMINI_MAX_DIMENSIONS) {
+      throw providerError(
+        "gemini",
+        `${GEMINI_MODEL} supports dimensions from ${GEMINI_MIN_DIMENSIONS} to ${GEMINI_MAX_DIMENSIONS}; received dimensions ${String(dimensions)}`
+      );
+    }
+    return effectiveDimensions;
   }
   if (provider === "mistral") {
     if (dimensions !== void 0 && dimensions !== MISTRAL_DIMENSIONS) {
@@ -361,16 +387,18 @@ class GeminiEmbeddingProvider {
       "API request",
       this.#timeoutMs,
       async (signal) => {
-        const { GoogleGenerativeAI } = await import('@google/generative-ai');
-        const genAI = new GoogleGenerativeAI(this.#apiKey);
-        const model = genAI.getGenerativeModel({ model: this.metadata.model });
+        const { GoogleGenAI } = await import('@google/genai');
+        const client = new GoogleGenAI({ apiKey: this.#apiKey });
         return embedSequentially("gemini", "API request", texts, signal, async (text, itemSignal) => {
-          const result = await model.embedContent(text, { signal: itemSignal });
-          const values = result.embedding?.values;
-          if (!Array.isArray(values)) {
-            throw new Error("Gemini response did not include embedding values");
-          }
-          return values;
+          const result = await client.models.embedContent({
+            model: this.metadata.model,
+            contents: formatGeminiEmbeddingContent(text, intent),
+            config: {
+              outputDimensionality: this.metadata.dimensions,
+              abortSignal: itemSignal
+            }
+          });
+          return parseGeminiEmbeddingResult(result);
         });
       },
       options.signal,
@@ -581,7 +609,9 @@ function createEmbeddingProvider(options = {}) {
     case "local":
       return new LocalEmbeddingProvider(metadata, timeoutMs);
     case "gemini": {
-      const key = options.apiKey || getEnvironmentVariable("GEMINI_API_KEY");
+      const key = getOptionalTrimmedCredential(
+        options.apiKey ?? getEnvironmentVariable("GEMINI_API_KEY")
+      );
       if (!key) {
         throw new Error("GEMINI_API_KEY is required for Gemini embeddings");
       }

package/docs/API.md

@@ -213,6 +213,9 @@ Hosted provider clients are scoped to their options. The library does not reuse
 a Cloudflare, Mistral, Gemini, or OpenAI client created with different
 credentials or configuration.
 
+Gemini uses `gemini-embedding-2`. Its default is 3072 dimensions, and explicit
+Gemini dimensions must be an integer from 128 through 3072.
+
 ### `getEmbeddingProviderMetadata(options?)`
 
 Returns the same metadata exposed by `createEmbeddingProvider(options).metadata`

package/docs/INDEXING.md

@@ -33,6 +33,14 @@ await indexContent({
 That keeps the implementation simple, but it also means a failed rebuild can
 leave the index partially repopulated.
 
+Changing an embedding provider or dimension count requires a full re-embed.
+For Gemini specifically, indexes created with the retired `text-embedding-004`
+model must be rebuilt for `gemini-embedding-2` even when staying at 768
+dimensions, because the model and query/document formatting both changed. If
+you adopt Gemini's 3072-dimensional default, recreate the vector table or build
+into a separate table first; clearing rows with `indexContent()` does not change
+the table's `F32_BLOB` width.
+
 ## Quality Guidelines
 
 - include descriptive frontmatter titles

package/docs/INTEGRATIONS.md

@@ -138,6 +138,8 @@ const embeddingProvider =
 const embeddingDimensions =
   embeddingProvider === "cloudflare" || embeddingProvider === "mistral"
     ? 1024
+    : embeddingProvider === "gemini"
+      ? 3072
     : 768;
 
 await createTable(client, "articles", embeddingDimensions);

package/docs/PROVIDERS.md

@@ -29,7 +29,8 @@ interface EmbeddingOptions {
 ```
 
 - `provider` defaults to `"local"`
-- `dimensions` defaults to `768`
+- `dimensions` defaults to `768` for the library's default local provider.
+  Provider-specific defaults can differ; Gemini defaults to `3072`.
 - `maxLength` defaults to `8000`
 - `intent` can be `"document"` or `"query"`; indexing defaults to
   `"document"` and search defaults to `"query"` unless explicitly set
@@ -176,22 +177,29 @@ Behavior:
 
 Provider value: `gemini`
 
-Gemini uses Google `text-embedding-004`.
+Gemini uses Google `gemini-embedding-2` through `@google/genai`.
 
 ```ts
 embeddingOptions: {
   provider: "gemini",
   apiKey: process.env.GEMINI_API_KEY,
+  dimensions: 3072,
 }
 ```
 
 Behavior:
 
 - if `apiKey` is omitted, the library reads `GEMINI_API_KEY`
-- Gemini returns 768 dimensions natively
-- metadata reports `text-embedding-004` and 768 dimensions
+- blank Gemini credentials are treated as missing
+- Gemini defaults to 3072 dimensions
+- explicit Gemini dimensions must be integers from 128 through 3072
+- 768, 1536, and 3072 are recommended practical sizes
+- metadata reports `gemini-embedding-2` and the effective dimensions
 - batch metadata is `{ mode: "sequential" }`
-- the current implementation does not expose model selection
+- the library sends one SDK request per input and verifies one vector per input
+- document inputs are formatted as `title: none | text: ...`
+- query inputs are formatted as `task: search result | query: ...`
+- the current implementation does not expose custom model selection
 
 ## OpenAI
 
@@ -223,9 +231,17 @@ Behavior:
 - `cloudflare` is fixed at `1024`
 - `mistral` is fixed at `1024`
 - local embeddings are padded from 384 to your target size
-- Gemini stays at 768
+- Gemini defaults to `3072` and accepts explicit dimensions from `128` through
+  `3072`; use `768`, `1536`, or `3072` unless you have a specific reason
 - OpenAI can be used at 1536 or 3072, or another supported OpenAI dimension
   value you explicitly set
 
 If you switch provider or dimensions for an existing table, recreate the table
 or rebuild the index into a separate table so stored vectors stay consistent.
+
+Existing Gemini indexes created with `text-embedding-004` must be fully
+re-embedded for `gemini-embedding-2`, even if you keep `dimensions: 768`,
+because both the model and query/document input formatting changed. If you move
+to the new 3072-dimensional default, create a new table or recreate the vector
+table first; `indexContent()` clears rows but does not change the `F32_BLOB`
+width. A separate table is safer because rebuilds are not transactional.

package/docs/TROUBLESHOOTING.md

@@ -12,3 +12,6 @@ Common operational checks:
 - verify hosted providers have `CLOUDFLARE_ACCOUNT_ID` and
   `CLOUDFLARE_API_TOKEN`, `MISTRAL_API_KEY`, `GEMINI_API_KEY`, or
   `OPENAI_API_KEY` available as required by the selected provider
+- after upgrading an existing Gemini index, fully re-embed with
+  `gemini-embedding-2`; for 3072-dimensional Gemini indexes, recreate the table
+  or use a new table name before rebuilding

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libsql-search",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Semantic search for static sites using libSQL/Turso with multi-provider embeddings",
   "type": "module",
   "packageManager": "pnpm@10.34.5",
@@ -66,9 +66,6 @@
     "@xenova/transformers": "^2.17.2",
     "gray-matter": "^4.0.3"
   },
-  "optionalDependencies": {
-    "@google/generative-ai": "^0.24.1"
-  },
   "devDependencies": {
     "@libsql/client": "^0.15.15",
     "@rollup/plugin-commonjs": "^29.0.3",
@@ -82,5 +79,8 @@
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11"
+  },
+  "optionalDependencies": {
+    "@google/genai": "2.18.0"
   }
 }