libsql-search 0.3.0 → 0.5.0

package/README.md

@@ -21,8 +21,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`, Google Gemini `text-embedding-004`, and OpenAI
-  `text-embedding-3-small` / `text-embedding-3-large`
+  `@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
 
 ## Install
@@ -98,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 and uses 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,10 +8,16 @@ 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";
+const MISTRAL_MODEL = "mistral-embed";
+const MISTRAL_EMBEDDINGS_URL = "https://api.mistral.ai/v1/embeddings";
+const MISTRAL_DIMENSIONS = 1024;
 const CLOUDFLARE_MODEL = "@cf/baai/bge-m3";
 const CLOUDFLARE_DIMENSIONS = 1024;
 const localModelCacheByModel = /* @__PURE__ */ new Map();
@@ -53,6 +59,7 @@ function resolveProviderName(provider) {
     case "local":
     case "gemini":
     case "openai":
+    case "mistral":
     case "cloudflare":
       return provider ?? "local";
     default:
@@ -81,6 +88,9 @@ function getOptionalTrimmedCredential(value) {
 function hasOwnProperty(value, property) {
   return Object.prototype.hasOwnProperty.call(value, property);
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
 function redactErrorText(value, exactSecrets = []) {
   let raw = value instanceof Error ? value.message : String(value);
   for (const secret of exactSecrets) {
@@ -114,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`);
@@ -232,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":
@@ -242,6 +268,13 @@ function createProviderMetadata(provider, dimensions) {
         dimensions,
         batch: Object.freeze({ mode: "native", maxSize: 2048 })
       });
+    case "mistral":
+      return Object.freeze({
+        name: "mistral",
+        model: MISTRAL_MODEL,
+        dimensions: MISTRAL_DIMENSIONS,
+        batch: Object.freeze({ mode: "native" })
+      });
     case "cloudflare":
       return Object.freeze({
         name: "cloudflare",
@@ -253,7 +286,23 @@ 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) {
+      throw providerError(
+        "mistral",
+        `${MISTRAL_MODEL} returns ${MISTRAL_DIMENSIONS} dimensions; received dimensions ${dimensions}`
+      );
+    }
+    return MISTRAL_DIMENSIONS;
   }
   if (provider === "cloudflare") {
     if (dimensions !== void 0 && dimensions !== CLOUDFLARE_DIMENSIONS) {
@@ -340,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,
@@ -362,6 +413,52 @@ class GeminiEmbeddingProvider {
     );
   }
 }
+async function requestOpenAICompatibleEmbeddings(request) {
+  const body = {
+    input: request.texts,
+    model: request.model
+  };
+  if (request.dimensions !== void 0) {
+    body.dimensions = request.dimensions;
+  }
+  if (request.encodingFormat !== void 0) {
+    body.encoding_format = request.encodingFormat;
+  }
+  const response = await fetch(request.endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${request.apiKey}`
+    },
+    signal: request.signal,
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    const requestId = getSafeResponseHeader(response, "x-request-id");
+    const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
+    throw new Error(context);
+  }
+  const data = await response.json();
+  if (!Array.isArray(data.data)) {
+    throw new Error(`${request.responseLabel} response did not include a data array`);
+  }
+  return data.data.map((item) => {
+    if (!isRecord(item)) {
+      throw new Error(`${request.responseLabel} response item was not an object`);
+    }
+    const embedding = item.embedding;
+    if (!Array.isArray(embedding)) {
+      throw new Error(`${request.responseLabel} response item did not include an embedding array`);
+    }
+    const parsed = { embedding };
+    if (hasOwnProperty(item, "index")) {
+      parsed.index = item.index;
+    } else if (request.requireIndex) {
+      throw new Error(`${request.responseLabel} response item did not include an index`);
+    }
+    return parsed;
+  });
+}
 class OpenAIEmbeddingProvider {
   metadata;
   #apiKey;
@@ -381,42 +478,15 @@ class OpenAIEmbeddingProvider {
       "openai",
       "API request",
       this.#timeoutMs,
-      async (signal) => {
-        const response = await fetch(OPENAI_EMBEDDINGS_URL, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.#apiKey}`
-          },
-          signal,
-          body: JSON.stringify({
-            input: texts,
-            model: this.metadata.model,
-            dimensions: this.metadata.dimensions
-          })
-        });
-        if (!response.ok) {
-          const requestId = getResponseHeader(response, "x-request-id");
-          const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
-          throw new Error(context);
-        }
-        const data = await response.json();
-        if (!Array.isArray(data.data)) {
-          throw new Error("OpenAI response did not include a data array");
-        }
-        return data.data.map((item) => {
-          const typed = item;
-          const embedding = typed.embedding;
-          if (!Array.isArray(embedding)) {
-            throw new Error("OpenAI response item did not include an embedding array");
-          }
-          const parsed = { embedding };
-          if (hasOwnProperty(typed, "index")) {
-            parsed.index = typed.index;
-          }
-          return parsed;
-        });
-      },
+      async (signal) => requestOpenAICompatibleEmbeddings({
+        responseLabel: "OpenAI",
+        endpoint: OPENAI_EMBEDDINGS_URL,
+        apiKey: this.#apiKey,
+        model: this.metadata.model,
+        texts,
+        signal,
+        dimensions: this.metadata.dimensions
+      }),
       options.signal,
       [this.#apiKey]
     );
@@ -427,6 +497,45 @@ class OpenAIEmbeddingProvider {
     );
   }
 }
+class MistralEmbeddingProvider {
+  metadata;
+  #apiKey;
+  #timeoutMs;
+  constructor(metadata, apiKey, timeoutMs) {
+    this.metadata = metadata;
+    this.#apiKey = apiKey;
+    this.#timeoutMs = timeoutMs;
+  }
+  async embed(texts, options = {}) {
+    const intent = resolveIntent(options.intent);
+    if (texts.length === 0) {
+      return createEmbeddingBatchResult(this.metadata, intent, []);
+    }
+    assertBatchSize(this.metadata, texts.length);
+    const items = await withTimeout(
+      "mistral",
+      "API request",
+      this.#timeoutMs,
+      async (signal) => requestOpenAICompatibleEmbeddings({
+        responseLabel: "Mistral",
+        endpoint: MISTRAL_EMBEDDINGS_URL,
+        apiKey: this.#apiKey,
+        model: this.metadata.model,
+        texts,
+        signal,
+        encodingFormat: "float",
+        requireIndex: true
+      }),
+      options.signal,
+      [this.#apiKey]
+    );
+    return createEmbeddingBatchResult(
+      this.metadata,
+      intent,
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "mistral")
+    );
+  }
+}
 class CloudflareEmbeddingProvider {
   metadata;
   #accountId;
@@ -502,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");
       }
@@ -515,6 +626,15 @@ function createEmbeddingProvider(options = {}) {
       }
       return new OpenAIEmbeddingProvider(metadata, key, timeoutMs);
     }
+    case "mistral": {
+      const key = getOptionalTrimmedCredential(
+        options.apiKey ?? getEnvironmentVariable("MISTRAL_API_KEY")
+      );
+      if (!key) {
+        throw new Error("MISTRAL_API_KEY is required for Mistral embeddings");
+      }
+      return new MistralEmbeddingProvider(metadata, key, timeoutMs);
+    }
     case "cloudflare": {
       const accountId = getOptionalTrimmedCredential(
         options.accountId ?? getEnvironmentVariable("CLOUDFLARE_ACCOUNT_ID")

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Client } from '@libsql/client';
 
-type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'cloudflare';
+type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'mistral' | 'cloudflare';
 type EmbeddingIntent = 'document' | 'query';
 type EmbeddingBatchMode = 'native' | 'sequential';
 interface EmbeddingBatchBehavior {

package/dist/index.esm.js

@@ -6,10 +6,16 @@ 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";
+const MISTRAL_MODEL = "mistral-embed";
+const MISTRAL_EMBEDDINGS_URL = "https://api.mistral.ai/v1/embeddings";
+const MISTRAL_DIMENSIONS = 1024;
 const CLOUDFLARE_MODEL = "@cf/baai/bge-m3";
 const CLOUDFLARE_DIMENSIONS = 1024;
 const localModelCacheByModel = /* @__PURE__ */ new Map();
@@ -51,6 +57,7 @@ function resolveProviderName(provider) {
     case "local":
     case "gemini":
     case "openai":
+    case "mistral":
     case "cloudflare":
       return provider ?? "local";
     default:
@@ -79,6 +86,9 @@ function getOptionalTrimmedCredential(value) {
 function hasOwnProperty(value, property) {
   return Object.prototype.hasOwnProperty.call(value, property);
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
 function redactErrorText(value, exactSecrets = []) {
   let raw = value instanceof Error ? value.message : String(value);
   for (const secret of exactSecrets) {
@@ -112,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`);
@@ -230,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":
@@ -240,6 +266,13 @@ function createProviderMetadata(provider, dimensions) {
         dimensions,
         batch: Object.freeze({ mode: "native", maxSize: 2048 })
       });
+    case "mistral":
+      return Object.freeze({
+        name: "mistral",
+        model: MISTRAL_MODEL,
+        dimensions: MISTRAL_DIMENSIONS,
+        batch: Object.freeze({ mode: "native" })
+      });
     case "cloudflare":
       return Object.freeze({
         name: "cloudflare",
@@ -251,7 +284,23 @@ 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) {
+      throw providerError(
+        "mistral",
+        `${MISTRAL_MODEL} returns ${MISTRAL_DIMENSIONS} dimensions; received dimensions ${dimensions}`
+      );
+    }
+    return MISTRAL_DIMENSIONS;
   }
   if (provider === "cloudflare") {
     if (dimensions !== void 0 && dimensions !== CLOUDFLARE_DIMENSIONS) {
@@ -338,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,
@@ -360,6 +411,52 @@ class GeminiEmbeddingProvider {
     );
   }
 }
+async function requestOpenAICompatibleEmbeddings(request) {
+  const body = {
+    input: request.texts,
+    model: request.model
+  };
+  if (request.dimensions !== void 0) {
+    body.dimensions = request.dimensions;
+  }
+  if (request.encodingFormat !== void 0) {
+    body.encoding_format = request.encodingFormat;
+  }
+  const response = await fetch(request.endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${request.apiKey}`
+    },
+    signal: request.signal,
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    const requestId = getSafeResponseHeader(response, "x-request-id");
+    const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
+    throw new Error(context);
+  }
+  const data = await response.json();
+  if (!Array.isArray(data.data)) {
+    throw new Error(`${request.responseLabel} response did not include a data array`);
+  }
+  return data.data.map((item) => {
+    if (!isRecord(item)) {
+      throw new Error(`${request.responseLabel} response item was not an object`);
+    }
+    const embedding = item.embedding;
+    if (!Array.isArray(embedding)) {
+      throw new Error(`${request.responseLabel} response item did not include an embedding array`);
+    }
+    const parsed = { embedding };
+    if (hasOwnProperty(item, "index")) {
+      parsed.index = item.index;
+    } else if (request.requireIndex) {
+      throw new Error(`${request.responseLabel} response item did not include an index`);
+    }
+    return parsed;
+  });
+}
 class OpenAIEmbeddingProvider {
   metadata;
   #apiKey;
@@ -379,42 +476,15 @@ class OpenAIEmbeddingProvider {
       "openai",
       "API request",
       this.#timeoutMs,
-      async (signal) => {
-        const response = await fetch(OPENAI_EMBEDDINGS_URL, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.#apiKey}`
-          },
-          signal,
-          body: JSON.stringify({
-            input: texts,
-            model: this.metadata.model,
-            dimensions: this.metadata.dimensions
-          })
-        });
-        if (!response.ok) {
-          const requestId = getResponseHeader(response, "x-request-id");
-          const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
-          throw new Error(context);
-        }
-        const data = await response.json();
-        if (!Array.isArray(data.data)) {
-          throw new Error("OpenAI response did not include a data array");
-        }
-        return data.data.map((item) => {
-          const typed = item;
-          const embedding = typed.embedding;
-          if (!Array.isArray(embedding)) {
-            throw new Error("OpenAI response item did not include an embedding array");
-          }
-          const parsed = { embedding };
-          if (hasOwnProperty(typed, "index")) {
-            parsed.index = typed.index;
-          }
-          return parsed;
-        });
-      },
+      async (signal) => requestOpenAICompatibleEmbeddings({
+        responseLabel: "OpenAI",
+        endpoint: OPENAI_EMBEDDINGS_URL,
+        apiKey: this.#apiKey,
+        model: this.metadata.model,
+        texts,
+        signal,
+        dimensions: this.metadata.dimensions
+      }),
       options.signal,
       [this.#apiKey]
     );
@@ -425,6 +495,45 @@ class OpenAIEmbeddingProvider {
     );
   }
 }
+class MistralEmbeddingProvider {
+  metadata;
+  #apiKey;
+  #timeoutMs;
+  constructor(metadata, apiKey, timeoutMs) {
+    this.metadata = metadata;
+    this.#apiKey = apiKey;
+    this.#timeoutMs = timeoutMs;
+  }
+  async embed(texts, options = {}) {
+    const intent = resolveIntent(options.intent);
+    if (texts.length === 0) {
+      return createEmbeddingBatchResult(this.metadata, intent, []);
+    }
+    assertBatchSize(this.metadata, texts.length);
+    const items = await withTimeout(
+      "mistral",
+      "API request",
+      this.#timeoutMs,
+      async (signal) => requestOpenAICompatibleEmbeddings({
+        responseLabel: "Mistral",
+        endpoint: MISTRAL_EMBEDDINGS_URL,
+        apiKey: this.#apiKey,
+        model: this.metadata.model,
+        texts,
+        signal,
+        encodingFormat: "float",
+        requireIndex: true
+      }),
+      options.signal,
+      [this.#apiKey]
+    );
+    return createEmbeddingBatchResult(
+      this.metadata,
+      intent,
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "mistral")
+    );
+  }
+}
 class CloudflareEmbeddingProvider {
   metadata;
   #accountId;
@@ -500,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");
       }
@@ -513,6 +624,15 @@ function createEmbeddingProvider(options = {}) {
       }
       return new OpenAIEmbeddingProvider(metadata, key, timeoutMs);
     }
+    case "mistral": {
+      const key = getOptionalTrimmedCredential(
+        options.apiKey ?? getEnvironmentVariable("MISTRAL_API_KEY")
+      );
+      if (!key) {
+        throw new Error("MISTRAL_API_KEY is required for Mistral embeddings");
+      }
+      return new MistralEmbeddingProvider(metadata, key, timeoutMs);
+    }
     case "cloudflare": {
       const accountId = getOptionalTrimmedCredential(
         options.accountId ?? getEnvironmentVariable("CLOUDFLARE_ACCOUNT_ID")

package/docs/API.md

@@ -210,8 +210,11 @@ Provider metadata includes:
 - `batch.maxSize`, when the provider has a hard maximum
 
 Hosted provider clients are scoped to their options. The library does not reuse
-a Cloudflare, Gemini, or OpenAI client created with different credentials or
-configuration.
+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?)`
 
@@ -239,7 +242,7 @@ Provider clients return:
 ```ts
 interface EmbeddingBatchResult {
   embeddings: number[][];
-  provider: "local" | "cloudflare" | "gemini" | "openai";
+  provider: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   model: string;
   dimensions: number;
   intent: "document" | "query";
@@ -255,7 +258,7 @@ cardinality, dimensions, finite numeric values, and indexed batch ordering.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "cloudflare" | "gemini" | "openai";
+  provider?: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   apiKey?: string;
   accountId?: string;
   apiToken?: string;
@@ -267,9 +270,10 @@ interface EmbeddingOptions {
 }
 ```
 
-`apiKey` is used by Gemini and OpenAI. Cloudflare uses `accountId` and
-`apiToken`, which fall back to `CLOUDFLARE_ACCOUNT_ID` and
-`CLOUDFLARE_API_TOKEN`.
+`apiKey` is used by Mistral, Gemini, and OpenAI. It falls back to
+`MISTRAL_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY` for those providers.
+Cloudflare uses `accountId` and `apiToken`, which fall back to
+`CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`.
 
 ### `padEmbedding(embedding, targetDimensions)`
 

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

@@ -128,8 +128,19 @@ const client = createClient({
 });
 
 const embeddingProvider =
-  process.env.EMBEDDING_PROVIDER as "local" | "cloudflare" | "gemini" | "openai" | undefined;
-const embeddingDimensions = embeddingProvider === "cloudflare" ? 1024 : 768;
+  process.env.EMBEDDING_PROVIDER as
+    | "local"
+    | "cloudflare"
+    | "mistral"
+    | "gemini"
+    | "openai"
+    | undefined;
+const embeddingDimensions =
+  embeddingProvider === "cloudflare" || embeddingProvider === "mistral"
+    ? 1024
+    : embeddingProvider === "gemini"
+      ? 3072
+    : 768;
 
 await createTable(client, "articles", embeddingDimensions);
 

package/docs/PROVIDERS.md

@@ -1,9 +1,10 @@
 # Embedding Providers
 
-`libsql-search` currently supports four embedding providers:
+`libsql-search` currently supports five embedding providers:
 
 - `local`
 - `cloudflare`
+- `mistral`
 - `gemini`
 - `openai`
 
@@ -15,7 +16,7 @@ query time.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "cloudflare" | "gemini" | "openai";
+  provider?: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   apiKey?: string;
   accountId?: string;
   apiToken?: string;
@@ -28,13 +29,14 @@ 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
 - `timeoutMs` defaults to `30000`
-- `apiKey` is used by Gemini and OpenAI and falls back to `GEMINI_API_KEY` or
-  `OPENAI_API_KEY`
+- `apiKey` is used by Mistral, Gemini, and OpenAI and falls back to
+  `MISTRAL_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY`
 - `accountId` and `apiToken` are used by Cloudflare and fall back to
   `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`
 
@@ -44,7 +46,7 @@ Each provider exposes immutable metadata:
 
 ```ts
 interface EmbeddingProviderMetadata {
-  name: "local" | "cloudflare" | "gemini" | "openai";
+  name: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   model: string;
   dimensions: number;
   batch: {
@@ -83,9 +85,9 @@ Lower-level provider clients return an `EmbeddingBatchResult` with the validated
 vectors plus provider, model, dimensions, and intent. The compatibility helpers
 `generateEmbedding()` and `generateEmbeddings()` return only arrays.
 
-Cloudflare, 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.
+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.
 
 Hosted provider failures are reported with bounded provider/status/request-id
 context and without raw upstream bodies, credentials, Authorization headers, or
@@ -144,26 +146,60 @@ Behavior:
 - Cloudflare does not accept custom dimensions in this provider; use
   `createTable(client, "articles", 1024)` for Cloudflare-backed indexes
 
+## Mistral
+
+Provider value: `mistral`
+
+Mistral uses the hosted `mistral-embed` model through
+`https://api.mistral.ai/v1/embeddings`.
+
+```ts
+embeddingOptions: {
+  provider: "mistral",
+  apiKey: process.env.MISTRAL_API_KEY,
+}
+```
+
+Behavior:
+
+- if `apiKey` is omitted, the library reads `MISTRAL_API_KEY`
+- blank Mistral credentials are treated as missing
+- `mistral-embed` returns 1024 dimensions
+- metadata reports `mistral-embed` and 1024 dimensions without requiring
+  credentials
+- batch metadata is `{ mode: "native" }`
+- request bodies send `encoding_format: "float"`
+- response items are reordered by provider-supplied index before being returned
+- Mistral does not accept custom dimensions in this provider; use
+  `createTable(client, "articles", 1024)` for Mistral-backed indexes
+
 ## Gemini
 
 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
 
@@ -193,10 +229,19 @@ Behavior:
 
 - `local` defaults to `768`
 - `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/README.md

@@ -3,8 +3,8 @@
 This directory holds the longer-form reference material for `libsql-search`.
 Start with the page that matches the job you are doing:
 
-- [Provider guide](./PROVIDERS.md): local, Gemini, and OpenAI embedding options,
-  dimensions, and API key behavior
+- [Provider guide](./PROVIDERS.md): local, Cloudflare, Mistral, Gemini, and
+  OpenAI embedding options, dimensions, and API key behavior
 - [API reference](./API.md): exported functions, option shapes, and result data
 - [Integration examples](./INTEGRATIONS.md): Astro and Next.js server-side usage
 - [Indexing and operations](./INDEXING.md): content layout, rebuild scripts,

package/docs/TROUBLESHOOTING.md

@@ -9,4 +9,9 @@ Common operational checks:
 - verify you called `createTable()` before indexing or searching
 - verify the table dimension matches the embedding dimension in your code
 - verify the same provider is used for indexing and querying
-- verify hosted providers have `GEMINI_API_KEY` or `OPENAI_API_KEY` available
+- 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.3.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"
   }
 }