libsql-search 0.4.0 → 0.6.0

package/README.md

@@ -20,9 +20,9 @@ Use it when you want:
 
 - Markdown indexing from local directories with frontmatter via `gray-matter`
 - 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` /
+- Embedding providers: local Hugging Face `Xenova/all-MiniLM-L6-v2`,
+  Cloudflare Workers AI `@cf/baai/bge-m3`, Mistral `mistral-embed`, Google Gemini
+  `gemini-embedding-2`, and OpenAI `text-embedding-3-small` /
   `text-embedding-3-large`
 - npm distribution plus JSR publishing
 
@@ -65,14 +65,13 @@ const client = createClient({
   authToken: "your-auth-token",
 });
 
-await createTable(client, "articles", 768);
+await createTable(client);
 
 await indexContent({
   client,
   contentPath: "./content",
   embeddingOptions: {
     provider: "local",
-    dimensions: 768,
   },
 });
 
@@ -82,7 +81,6 @@ const results = await search({
   limit: 5,
   embeddingOptions: {
     provider: "local",
-    dimensions: 768,
   },
 });
 
@@ -98,8 +96,9 @@ Important behavior:
 - Call `createTable()` before indexing or searching.
 - 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.
+- `local` is the default offline provider and uses 384 dimensions. Cloudflare is
+  the recommended hosted option. Cloudflare and Mistral use 1024 dimensions.
+  Gemini defaults to 3072 dimensions and supports 128-3072.
 
 ## Core API
 

package/dist/index.cjs

@@ -4,11 +4,15 @@ var promises = require('fs/promises');
 var path = require('path');
 var matter = require('gray-matter');
 
-const DEFAULT_DIMENSIONS = 768;
+const OPENAI_DEFAULT_DIMENSIONS = 768;
+const LOCAL_DIMENSIONS = 384;
 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";
@@ -30,17 +34,66 @@ function getEnvironmentVariable(name) {
     return void 0;
   }
 }
-async function getLocalEmbeddingModel(modelName) {
+function deletePendingLocalModelCache(modelName, entry) {
+  if (!entry.settled && entry.waiters === 0 && localModelCacheByModel.get(modelName) === entry) {
+    localModelCacheByModel.delete(modelName);
+  }
+}
+async function getLocalEmbeddingModel(modelName, signal) {
   const cached = localModelCacheByModel.get(modelName);
-  if (cached?.model) {
-    return cached.model;
+  if (cached) {
+    cached.waiters++;
+    try {
+      return await waitForLocalEmbeddingModel(modelName, cached, signal);
+    } finally {
+      cached.waiters--;
+      deletePendingLocalModelCache(modelName, cached);
+    }
+  }
+  const modelPromise = (async () => {
+    console.log(`Loading local embedding model (${modelName})...`);
+    const { pipeline } = await import('@huggingface/transformers');
+    const model = await pipeline("feature-extraction", modelName);
+    console.log("Local model loaded successfully");
+    return model;
+  })();
+  const entry = {
+    promise: modelPromise,
+    settled: false,
+    waiters: 1
+  };
+  localModelCacheByModel.set(modelName, entry);
+  modelPromise.then(() => {
+    entry.settled = true;
+  }).catch(() => {
+    localModelCacheByModel.delete(modelName);
+  });
+  try {
+    return await waitForLocalEmbeddingModel(modelName, entry, signal);
+  } finally {
+    entry.waiters--;
+    deletePendingLocalModelCache(modelName, entry);
+  }
+}
+async function waitForLocalEmbeddingModel(modelName, entry, signal) {
+  if (signal.aborted) {
+    deletePendingLocalModelCache(modelName, entry);
+    throw providerError("local", "model inference was aborted");
+  }
+  let rejectAbort = () => {
+  };
+  const abortPromise = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const onAbort = () => {
+    rejectAbort(providerError("local", "model inference was aborted"));
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await Promise.race([entry.promise, abortPromise]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
   }
-  console.log(`Loading local embedding model (${modelName})...`);
-  const { pipeline } = await import('@xenova/transformers');
-  const model = await pipeline("feature-extraction", modelName);
-  localModelCacheByModel.set(modelName, { model });
-  console.log("Local model loaded successfully");
-  return model;
 }
 function getPositiveInteger(value, optionName) {
   if (!Number.isInteger(value) || value <= 0) {
@@ -121,6 +174,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 +308,7 @@ function createProviderMetadata(provider, dimensions) {
       return Object.freeze({
         name: "gemini",
         model: GEMINI_MODEL,
-        dimensions: DEFAULT_DIMENSIONS,
+        dimensions,
         batch: Object.freeze({ mode: "sequential" })
       });
     case "openai":
@@ -266,8 +335,24 @@ function createProviderMetadata(provider, dimensions) {
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
+  if (provider === "local") {
+    if (dimensions !== void 0 && dimensions !== LOCAL_DIMENSIONS) {
+      throw providerError(
+        "local",
+        `${LOCAL_MODEL} returns ${LOCAL_DIMENSIONS} dimensions; received dimensions ${String(dimensions)}`
+      );
+    }
+    return LOCAL_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) {
@@ -287,7 +372,7 @@ function getEffectiveDimensions(provider, dimensions) {
     }
     return CLOUDFLARE_DIMENSIONS;
   }
-  return getPositiveInteger(dimensions ?? DEFAULT_DIMENSIONS, "dimensions");
+  return getPositiveInteger(dimensions ?? OPENAI_DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
   if (metadata.batch.maxSize !== void 0 && count > metadata.batch.maxSize) {
@@ -324,14 +409,13 @@ class LocalEmbeddingProvider {
       "model inference",
       this.#timeoutMs,
       async (signal) => {
-        const model = await getLocalEmbeddingModel(this.metadata.model);
+        const model = await getLocalEmbeddingModel(this.metadata.model, signal);
         return embedSequentially("local", "model inference", texts, signal, async (text) => {
           const output = await model(text, {
             pooling: "mean",
             normalize: true
           });
-          const embedding = Array.from(output.data);
-          return padEmbedding(embedding, this.metadata.dimensions);
+          return Array.from(output.data);
         });
       },
       options.signal
@@ -363,16 +447,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 +669,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");
       }
@@ -794,7 +882,7 @@ async function insertDocument(client, document, quotedTableName) {
     ]
   });
 }
-async function createTable(client, tableName = "articles", dimensions = 768) {
+async function createTable(client, tableName = "articles", dimensions = 384) {
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
   const vectorDimensions = normalizeVectorDimensions(dimensions);
   const quotedEmbeddingIndexName = quoteSqlIdentifier(`${tableName}_embedding_idx`, "embedding index name");

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 import { Client } from '@libsql/client';
 
+/**
+ * Multi-provider embedding generation
+ * Supports local Hugging Face Transformers, Gemini, OpenAI, Mistral, and Cloudflare Workers AI
+ */
 type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'mistral' | 'cloudflare';
 type EmbeddingIntent = 'document' | 'query';
 type EmbeddingBatchMode = 'native' | 'sequential';

package/dist/index.esm.js

@@ -2,11 +2,15 @@ import { readdir, readFile } from 'fs/promises';
 import { join, extname, relative, dirname } from 'path';
 import matter from 'gray-matter';
 
-const DEFAULT_DIMENSIONS = 768;
+const OPENAI_DEFAULT_DIMENSIONS = 768;
+const LOCAL_DIMENSIONS = 384;
 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";
@@ -28,17 +32,66 @@ function getEnvironmentVariable(name) {
     return void 0;
   }
 }
-async function getLocalEmbeddingModel(modelName) {
+function deletePendingLocalModelCache(modelName, entry) {
+  if (!entry.settled && entry.waiters === 0 && localModelCacheByModel.get(modelName) === entry) {
+    localModelCacheByModel.delete(modelName);
+  }
+}
+async function getLocalEmbeddingModel(modelName, signal) {
   const cached = localModelCacheByModel.get(modelName);
-  if (cached?.model) {
-    return cached.model;
+  if (cached) {
+    cached.waiters++;
+    try {
+      return await waitForLocalEmbeddingModel(modelName, cached, signal);
+    } finally {
+      cached.waiters--;
+      deletePendingLocalModelCache(modelName, cached);
+    }
+  }
+  const modelPromise = (async () => {
+    console.log(`Loading local embedding model (${modelName})...`);
+    const { pipeline } = await import('@huggingface/transformers');
+    const model = await pipeline("feature-extraction", modelName);
+    console.log("Local model loaded successfully");
+    return model;
+  })();
+  const entry = {
+    promise: modelPromise,
+    settled: false,
+    waiters: 1
+  };
+  localModelCacheByModel.set(modelName, entry);
+  modelPromise.then(() => {
+    entry.settled = true;
+  }).catch(() => {
+    localModelCacheByModel.delete(modelName);
+  });
+  try {
+    return await waitForLocalEmbeddingModel(modelName, entry, signal);
+  } finally {
+    entry.waiters--;
+    deletePendingLocalModelCache(modelName, entry);
+  }
+}
+async function waitForLocalEmbeddingModel(modelName, entry, signal) {
+  if (signal.aborted) {
+    deletePendingLocalModelCache(modelName, entry);
+    throw providerError("local", "model inference was aborted");
+  }
+  let rejectAbort = () => {
+  };
+  const abortPromise = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const onAbort = () => {
+    rejectAbort(providerError("local", "model inference was aborted"));
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await Promise.race([entry.promise, abortPromise]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
   }
-  console.log(`Loading local embedding model (${modelName})...`);
-  const { pipeline } = await import('@xenova/transformers');
-  const model = await pipeline("feature-extraction", modelName);
-  localModelCacheByModel.set(modelName, { model });
-  console.log("Local model loaded successfully");
-  return model;
 }
 function getPositiveInteger(value, optionName) {
   if (!Number.isInteger(value) || value <= 0) {
@@ -119,6 +172,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 +306,7 @@ function createProviderMetadata(provider, dimensions) {
       return Object.freeze({
         name: "gemini",
         model: GEMINI_MODEL,
-        dimensions: DEFAULT_DIMENSIONS,
+        dimensions,
         batch: Object.freeze({ mode: "sequential" })
       });
     case "openai":
@@ -264,8 +333,24 @@ function createProviderMetadata(provider, dimensions) {
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
+  if (provider === "local") {
+    if (dimensions !== void 0 && dimensions !== LOCAL_DIMENSIONS) {
+      throw providerError(
+        "local",
+        `${LOCAL_MODEL} returns ${LOCAL_DIMENSIONS} dimensions; received dimensions ${String(dimensions)}`
+      );
+    }
+    return LOCAL_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) {
@@ -285,7 +370,7 @@ function getEffectiveDimensions(provider, dimensions) {
     }
     return CLOUDFLARE_DIMENSIONS;
   }
-  return getPositiveInteger(dimensions ?? DEFAULT_DIMENSIONS, "dimensions");
+  return getPositiveInteger(dimensions ?? OPENAI_DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
   if (metadata.batch.maxSize !== void 0 && count > metadata.batch.maxSize) {
@@ -322,14 +407,13 @@ class LocalEmbeddingProvider {
       "model inference",
       this.#timeoutMs,
       async (signal) => {
-        const model = await getLocalEmbeddingModel(this.metadata.model);
+        const model = await getLocalEmbeddingModel(this.metadata.model, signal);
         return embedSequentially("local", "model inference", texts, signal, async (text) => {
           const output = await model(text, {
             pooling: "mean",
             normalize: true
           });
-          const embedding = Array.from(output.data);
-          return padEmbedding(embedding, this.metadata.dimensions);
+          return Array.from(output.data);
         });
       },
       options.signal
@@ -361,16 +445,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 +667,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");
       }
@@ -792,7 +880,7 @@ async function insertDocument(client, document, quotedTableName) {
     ]
   });
 }
-async function createTable(client, tableName = "articles", dimensions = 768) {
+async function createTable(client, tableName = "articles", dimensions = 384) {
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
   const vectorDimensions = normalizeVectorDimensions(dimensions);
   const quotedEmbeddingIndexName = quoteSqlIdentifier(`${tableName}_embedding_idx`, "embedding index name");

package/docs/API.md

@@ -42,13 +42,13 @@ It also exports these types:
 Creates the table and supporting indexes used by search.
 
 ```ts
-await createTable(client, "articles", 768);
+await createTable(client);
 ```
 
 Defaults:
 
 - `tableName`: `"articles"`
-- `dimensions`: `768`
+- `dimensions`: `384`
 
 `tableName` must be an ASCII SQLite identifier matching
 `[A-Za-z_][A-Za-z0-9_]*`. Valid identifiers are quoted internally, so reserved
@@ -213,6 +213,13 @@ 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.
+
+Local embeddings use `Xenova/all-MiniLM-L6-v2` through
+`@huggingface/transformers` and are fixed at the model's native 384 dimensions.
+Passing any other local dimension is rejected before the runtime is loaded.
+
 ### `getEmbeddingProviderMetadata(options?)`
 
 Returns the same metadata exposed by `createEmbeddingProvider(options).metadata`
@@ -276,6 +283,9 @@ Cloudflare uses `accountId` and `apiToken`, which fall back to
 
 Pads or truncates an embedding array to the requested length.
 
+This helper remains exported for callers that used it directly. The local
+provider does not use it; local vectors are validated at native 384 dimensions.
+
 ### `prepareTextForEmbedding(fields)`
 
 Combines title, description, tags, and content into the text sent to the

package/docs/INDEXING.md

@@ -25,7 +25,6 @@ await indexContent({
   tableName: "articles",
   embeddingOptions: {
     provider: "local",
-    dimensions: 768,
   },
 });
 ```
@@ -33,6 +32,19 @@ 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 existing local indexes created with the older padded-local behavior, create
+or recreate a 384-dimensional table before rebuilding. Those older local
+768-dimensional tables stored 384 model values followed by zero padding;
+`indexContent()` clears rows but does not change the table's `F32_BLOB` width.
+
+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
@@ -64,7 +76,7 @@ database calls or embedding generation.
 
 ## Runtime Notes
 
-- local embeddings may download a model on the first run
+- local embeddings may download and cache a model on the first run
 - Node users need `@libsql/client` installed alongside the package
 - the repository validates both the npm package build and `deno check`, but the
   indexing flow itself still depends on filesystem access

package/docs/INTEGRATIONS.md

@@ -26,7 +26,6 @@ export const POST: APIRoute = async ({ request }) => {
     limit,
     embeddingOptions: {
       provider: "local",
-      dimensions: 768,
     },
   });
 
@@ -79,7 +78,6 @@ export async function POST(request: NextRequest) {
     limit,
     embeddingOptions: {
       provider: "local",
-      dimensions: 768,
     },
   });
 
@@ -135,10 +133,16 @@ const embeddingProvider =
     | "gemini"
     | "openai"
     | undefined;
-const embeddingDimensions =
-  embeddingProvider === "cloudflare" || embeddingProvider === "mistral"
-    ? 1024
-    : 768;
+
+const dimensionsByProvider = {
+  local: 384,
+  cloudflare: 1024,
+  mistral: 1024,
+  gemini: 3072,
+  openai: 1536,
+} as const;
+
+const embeddingDimensions = dimensionsByProvider[embeddingProvider ?? "local"];
 
 await createTable(client, "articles", embeddingDimensions);
 

package/docs/PROVIDERS.md

@@ -29,7 +29,9 @@ interface EmbeddingOptions {
 ```
 
 - `provider` defaults to `"local"`
-- `dimensions` defaults to `768`
+- `dimensions` defaults to `384` for the library's default local provider.
+  Provider-specific defaults can differ; Cloudflare and Mistral use `1024`,
+  and 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
@@ -86,7 +88,8 @@ vectors plus provider, model, dimensions, and intent. The compatibility helpers
 
 Cloudflare, Mistral, Gemini, and OpenAI clients are scoped to their current
 options. They are not cached globally across different credentials or
-configurations. The local Xenova model can be cached by model name.
+configurations. The local Hugging Face Transformers pipeline is loaded lazily
+and cached by model name.
 
 Hosted provider failures are reported with bounded provider/status/request-id
 context and without raw upstream bodies, credentials, Authorization headers, or
@@ -97,24 +100,26 @@ full URLs with query strings.
 Provider value: `local`
 
 The local provider loads `Xenova/all-MiniLM-L6-v2` through
-`@xenova/transformers`.
+`@huggingface/transformers`.
 
 ```ts
 embeddingOptions: {
   provider: "local",
-  dimensions: 768,
 }
 ```
 
 Notes:
 
-- the model emits 384 dimensions and `libsql-search` pads or truncates to your
-  requested size
-- metadata reports the requested output dimensions
+- the model emits 384 dimensions, and local vectors are validated at exactly
+  384 finite numbers
+- `dimensions: 384` is accepted explicitly; any other local dimension is
+  rejected before the runtime is imported or loaded
+- metadata reports 384 dimensions
 - batch metadata is `{ mode: "sequential" }`
-- the first run downloads the model and can take longer on a fresh machine
+- the first run downloads and caches the model and can take longer on a fresh
+  machine
 - no API key is required
-- this remains the default provider for backward compatibility and offline use
+- this remains the default provider for offline use
 
 ## Cloudflare Workers AI
 
@@ -176,22 +181,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
 
@@ -219,13 +231,31 @@ Behavior:
 
 ## Dimension Guidelines
 
-- `local` defaults to `768`
+- `local` is fixed at `384`
 - `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.
+
+Existing local indexes created with the older padded-local behavior usually have
+`F32_BLOB(768)` rows containing the 384 model values followed by zero padding.
+The current local contract stores the native 384-dimensional model output. To
+migrate, create or recreate a `F32_BLOB(384)` table and run a full re-index
+before querying it. Using the same model ID avoids an intentional model-space
+change, but bit-identical vectors are not promised across runtime, model
+revision, dtype, pooling, or normalization changes; validate search quality and
+re-index when those details change.
+
+Routine unit tests mock the local runtime and do not download the model.

package/docs/TROUBLESHOOTING-SHARP.md

@@ -1,11 +1,12 @@
 # Troubleshooting: Transitive `sharp` Install Errors
 
-`libsql-search` does not directly depend on `sharp`. If you see an install error
-mentioning `sharp`, it is coming from another dependency in your application or
-toolchain.
+`libsql-search` does not directly import `sharp`, but local embeddings use
+`@huggingface/transformers`, which currently brings in `sharp` as a transitive
+runtime dependency. If you see an install error mentioning `sharp`, it is
+usually a native-package install or approval issue.
 
-This page exists because the error can show up in environments that also use
-`libsql-search`, and it is easy to misattribute the failure to this package.
+This page exists because the error can show up before your application reaches
+any `libsql-search` code.
 
 ## Typical Error
 
@@ -48,7 +49,7 @@ in `pnpm-workspace.yaml` with `onlyBuiltDependencies`.
 
 ## Relation To `libsql-search`
 
-- local embeddings use `@xenova/transformers`
+- local embeddings use `@huggingface/transformers`
 - the first local embedding run may download a model at runtime
 - that runtime model download is separate from a pnpm native-module install
   failure

package/docs/TROUBLESHOOTING.md

@@ -12,3 +12,8 @@ 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
+- after upgrading an existing local 768-dimensional padded index, create or
+  recreate a 384-dimensional table and fully re-index before querying it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libsql-search",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Semantic search for static sites using libSQL/Turso with multi-provider embeddings",
   "type": "module",
   "packageManager": "pnpm@10.34.5",
@@ -63,12 +63,9 @@
     "@libsql/client": "^0.15.0"
   },
   "dependencies": {
-    "@xenova/transformers": "^2.17.2",
+    "@huggingface/transformers": "4.2.0",
     "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"
   }
 }