libsql-search 0.2.4 → 0.4.0

package/README.md

@@ -13,16 +13,17 @@ Use it when you want:
 
 - a small TypeScript library instead of a hosted search product
 - one search index shared across static-site builds and app routes
-- local or API-based embeddings behind the same indexing/search API
+- local or hosted embeddings behind the same indexing/search API
 - direct control over table names, dimensions, content shape, and deployment
 
 ## What It Supports
 
 - Markdown indexing from local directories with frontmatter via `gray-matter`
 - libSQL/Turso storage and vector search
-- Embedding providers that exist in the code today: local
-  `Xenova/all-MiniLM-L6-v2`, Google Gemini `text-embedding-004`, and OpenAI
-  `text-embedding-3-small` and `text-embedding-3-large`
+- 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` /
+  `text-embedding-3-large`
 - npm distribution plus JSR publishing
 
 ## Install
@@ -97,6 +98,8 @@ 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.
 
 ## Core API
 

package/dist/index.cjs

@@ -12,6 +12,11 @@ const GEMINI_MODEL = "text-embedding-004";
 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();
 function getEnvironmentVariable(name) {
   const runtime = globalThis;
@@ -51,6 +56,8 @@ function resolveProviderName(provider) {
     case "local":
     case "gemini":
     case "openai":
+    case "mistral":
+    case "cloudflare":
       return provider ?? "local";
     default:
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
@@ -71,9 +78,16 @@ function truncateTexts(texts, maxLength) {
 function getOpenAIModel(dimensions) {
   return dimensions <= 1536 ? OPENAI_SMALL_MODEL : OPENAI_LARGE_MODEL;
 }
+function getOptionalTrimmedCredential(value) {
+  const trimmed = value?.trim();
+  return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
+}
 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) {
@@ -97,6 +111,16 @@ function providerError(provider, message, cause, exactSecrets = []) {
 function getResponseHeader(response, name) {
   return response.headers.get(name) ?? void 0;
 }
+function getSafeResponseHeader(response, name) {
+  const value = getResponseHeader(response, name)?.trim();
+  if (!value) {
+    return void 0;
+  }
+  return value.replace(/[^A-Za-z0-9._:-]/g, "").slice(0, 128);
+}
+function createCloudflareEmbeddingsUrl(accountId) {
+  return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/v1/embeddings`;
+}
 async function withTimeout(provider, operation, timeoutMs, run, parentSignal, exactSecrets = []) {
   if (parentSignal?.aborted) {
     throw providerError(provider, `${operation} was aborted`);
@@ -225,12 +249,44 @@ 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",
+        model: CLOUDFLARE_MODEL,
+        dimensions: CLOUDFLARE_DIMENSIONS,
+        batch: Object.freeze({ mode: "native" })
+      });
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
   if (provider === "gemini") {
     return DEFAULT_DIMENSIONS;
   }
+  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) {
+      throw providerError(
+        "cloudflare",
+        `@cf/baai/bge-m3 returns ${CLOUDFLARE_DIMENSIONS} dimensions; received dimensions ${dimensions}`
+      );
+    }
+    return CLOUDFLARE_DIMENSIONS;
+  }
   return getPositiveInteger(dimensions ?? DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
@@ -329,6 +385,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;
@@ -348,34 +450,113 @@ class OpenAIEmbeddingProvider {
       "openai",
       "API request",
       this.#timeoutMs,
+      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]
+    );
+    return createEmbeddingBatchResult(
+      this.metadata,
+      intent,
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "openai")
+    );
+  }
+}
+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;
+  #apiToken;
+  #timeoutMs;
+  constructor(metadata, accountId, apiToken, timeoutMs) {
+    this.metadata = metadata;
+    this.#accountId = accountId;
+    this.#apiToken = apiToken;
+    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 endpoint = createCloudflareEmbeddingsUrl(this.#accountId);
+    const items = await withTimeout(
+      "cloudflare",
+      "API request",
+      this.#timeoutMs,
       async (signal) => {
-        const response = await fetch(OPENAI_EMBEDDINGS_URL, {
+        const response = await fetch(endpoint, {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.#apiKey}`
+            "Authorization": `Bearer ${this.#apiToken}`
           },
           signal,
           body: JSON.stringify({
-            input: texts,
             model: this.metadata.model,
-            dimensions: this.metadata.dimensions
+            input: texts
           })
         });
         if (!response.ok) {
-          const requestId = getResponseHeader(response, "x-request-id");
-          const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
+          const cfRay = getSafeResponseHeader(response, "cf-ray");
+          const context = cfRay ? ` status ${response.status}, cf-ray ${cfRay}` : ` 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");
+          throw new Error("Cloudflare 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");
+            throw new Error("Cloudflare response item did not include an embedding array");
           }
           const parsed = { embedding };
           if (hasOwnProperty(typed, "index")) {
@@ -385,12 +566,12 @@ class OpenAIEmbeddingProvider {
         });
       },
       options.signal,
-      [this.#apiKey]
+      [this.#apiToken, this.#accountId, encodeURIComponent(this.#accountId)]
     );
     return createEmbeddingBatchResult(
       this.metadata,
       intent,
-      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "openai")
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "cloudflare")
     );
   }
 }
@@ -415,6 +596,30 @@ 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")
+      );
+      const apiToken = getOptionalTrimmedCredential(
+        options.apiToken ?? getEnvironmentVariable("CLOUDFLARE_API_TOKEN")
+      );
+      if (!accountId) {
+        throw new Error("CLOUDFLARE_ACCOUNT_ID is required for Cloudflare embeddings");
+      }
+      if (!apiToken) {
+        throw new Error("CLOUDFLARE_API_TOKEN is required for Cloudflare embeddings");
+      }
+      return new CloudflareEmbeddingProvider(metadata, accountId, apiToken, timeoutMs);
+    }
   }
 }
 function getEmbeddingProviderMetadata(options = {}) {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Client } from '@libsql/client';
 
-type EmbeddingProvider = 'local' | 'gemini' | 'openai';
+type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'mistral' | 'cloudflare';
 type EmbeddingIntent = 'document' | 'query';
 type EmbeddingBatchMode = 'native' | 'sequential';
 interface EmbeddingBatchBehavior {
@@ -31,6 +31,8 @@ interface EmbeddingBatchResult {
 interface EmbeddingOptions {
     provider?: EmbeddingProvider;
     apiKey?: string;
+    accountId?: string;
+    apiToken?: string;
     dimensions?: number;
     maxLength?: number;
     intent?: EmbeddingIntent;

package/dist/index.esm.js

@@ -10,6 +10,11 @@ const GEMINI_MODEL = "text-embedding-004";
 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();
 function getEnvironmentVariable(name) {
   const runtime = globalThis;
@@ -49,6 +54,8 @@ function resolveProviderName(provider) {
     case "local":
     case "gemini":
     case "openai":
+    case "mistral":
+    case "cloudflare":
       return provider ?? "local";
     default:
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
@@ -69,9 +76,16 @@ function truncateTexts(texts, maxLength) {
 function getOpenAIModel(dimensions) {
   return dimensions <= 1536 ? OPENAI_SMALL_MODEL : OPENAI_LARGE_MODEL;
 }
+function getOptionalTrimmedCredential(value) {
+  const trimmed = value?.trim();
+  return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
+}
 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) {
@@ -95,6 +109,16 @@ function providerError(provider, message, cause, exactSecrets = []) {
 function getResponseHeader(response, name) {
   return response.headers.get(name) ?? void 0;
 }
+function getSafeResponseHeader(response, name) {
+  const value = getResponseHeader(response, name)?.trim();
+  if (!value) {
+    return void 0;
+  }
+  return value.replace(/[^A-Za-z0-9._:-]/g, "").slice(0, 128);
+}
+function createCloudflareEmbeddingsUrl(accountId) {
+  return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/ai/v1/embeddings`;
+}
 async function withTimeout(provider, operation, timeoutMs, run, parentSignal, exactSecrets = []) {
   if (parentSignal?.aborted) {
     throw providerError(provider, `${operation} was aborted`);
@@ -223,12 +247,44 @@ 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",
+        model: CLOUDFLARE_MODEL,
+        dimensions: CLOUDFLARE_DIMENSIONS,
+        batch: Object.freeze({ mode: "native" })
+      });
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
   if (provider === "gemini") {
     return DEFAULT_DIMENSIONS;
   }
+  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) {
+      throw providerError(
+        "cloudflare",
+        `@cf/baai/bge-m3 returns ${CLOUDFLARE_DIMENSIONS} dimensions; received dimensions ${dimensions}`
+      );
+    }
+    return CLOUDFLARE_DIMENSIONS;
+  }
   return getPositiveInteger(dimensions ?? DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
@@ -327,6 +383,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;
@@ -346,34 +448,113 @@ class OpenAIEmbeddingProvider {
       "openai",
       "API request",
       this.#timeoutMs,
+      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]
+    );
+    return createEmbeddingBatchResult(
+      this.metadata,
+      intent,
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "openai")
+    );
+  }
+}
+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;
+  #apiToken;
+  #timeoutMs;
+  constructor(metadata, accountId, apiToken, timeoutMs) {
+    this.metadata = metadata;
+    this.#accountId = accountId;
+    this.#apiToken = apiToken;
+    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 endpoint = createCloudflareEmbeddingsUrl(this.#accountId);
+    const items = await withTimeout(
+      "cloudflare",
+      "API request",
+      this.#timeoutMs,
       async (signal) => {
-        const response = await fetch(OPENAI_EMBEDDINGS_URL, {
+        const response = await fetch(endpoint, {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.#apiKey}`
+            "Authorization": `Bearer ${this.#apiToken}`
           },
           signal,
           body: JSON.stringify({
-            input: texts,
             model: this.metadata.model,
-            dimensions: this.metadata.dimensions
+            input: texts
           })
         });
         if (!response.ok) {
-          const requestId = getResponseHeader(response, "x-request-id");
-          const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
+          const cfRay = getSafeResponseHeader(response, "cf-ray");
+          const context = cfRay ? ` status ${response.status}, cf-ray ${cfRay}` : ` 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");
+          throw new Error("Cloudflare 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");
+            throw new Error("Cloudflare response item did not include an embedding array");
           }
           const parsed = { embedding };
           if (hasOwnProperty(typed, "index")) {
@@ -383,12 +564,12 @@ class OpenAIEmbeddingProvider {
         });
       },
       options.signal,
-      [this.#apiKey]
+      [this.#apiToken, this.#accountId, encodeURIComponent(this.#accountId)]
     );
     return createEmbeddingBatchResult(
       this.metadata,
       intent,
-      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "openai")
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "cloudflare")
     );
   }
 }
@@ -413,6 +594,30 @@ 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")
+      );
+      const apiToken = getOptionalTrimmedCredential(
+        options.apiToken ?? getEnvironmentVariable("CLOUDFLARE_API_TOKEN")
+      );
+      if (!accountId) {
+        throw new Error("CLOUDFLARE_ACCOUNT_ID is required for Cloudflare embeddings");
+      }
+      if (!apiToken) {
+        throw new Error("CLOUDFLARE_API_TOKEN is required for Cloudflare embeddings");
+      }
+      return new CloudflareEmbeddingProvider(metadata, accountId, apiToken, timeoutMs);
+    }
   }
 }
 function getEmbeddingProviderMetadata(options = {}) {

package/docs/API.md

@@ -210,7 +210,8 @@ 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 Gemini or OpenAI client created with a different API key or configuration.
+a Cloudflare, Mistral, Gemini, or OpenAI client created with different
+credentials or configuration.
 
 ### `getEmbeddingProviderMetadata(options?)`
 
@@ -238,7 +239,7 @@ Provider clients return:
 ```ts
 interface EmbeddingBatchResult {
   embeddings: number[][];
-  provider: "local" | "gemini" | "openai";
+  provider: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   model: string;
   dimensions: number;
   intent: "document" | "query";
@@ -254,8 +255,10 @@ cardinality, dimensions, finite numeric values, and indexed batch ordering.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "gemini" | "openai";
+  provider?: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   apiKey?: string;
+  accountId?: string;
+  apiToken?: string;
   dimensions?: number;
   maxLength?: number;
   intent?: "document" | "query";
@@ -264,6 +267,11 @@ interface EmbeddingOptions {
 }
 ```
 
+`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)`
 
 Pads or truncates an embedding array to the requested length.

package/docs/INTEGRATIONS.md

@@ -127,14 +127,27 @@ const client = createClient({
   authToken: process.env.TURSO_AUTH_TOKEN!,
 });
 
-await createTable(client, "articles", 768);
+const embeddingProvider =
+  process.env.EMBEDDING_PROVIDER as
+    | "local"
+    | "cloudflare"
+    | "mistral"
+    | "gemini"
+    | "openai"
+    | undefined;
+const embeddingDimensions =
+  embeddingProvider === "cloudflare" || embeddingProvider === "mistral"
+    ? 1024
+    : 768;
+
+await createTable(client, "articles", embeddingDimensions);
 
 await indexContent({
   client,
   contentPath: "./content",
   embeddingOptions: {
-    provider: process.env.EMBEDDING_PROVIDER as "local" | "gemini" | "openai" | undefined,
-    dimensions: 768,
+    provider: embeddingProvider,
+    dimensions: embeddingDimensions,
   },
 });
 ```

package/docs/PROVIDERS.md

@@ -1,8 +1,10 @@
 # Embedding Providers
 
-`libsql-search` currently supports three embedding providers:
+`libsql-search` currently supports five embedding providers:
 
 - `local`
+- `cloudflare`
+- `mistral`
 - `gemini`
 - `openai`
 
@@ -14,8 +16,10 @@ query time.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "gemini" | "openai";
+  provider?: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   apiKey?: string;
+  accountId?: string;
+  apiToken?: string;
   dimensions?: number;
   maxLength?: number;
   intent?: "document" | "query";
@@ -30,8 +34,10 @@ interface EmbeddingOptions {
 - `intent` can be `"document"` or `"query"`; indexing defaults to
   `"document"` and search defaults to `"query"` unless explicitly set
 - `timeoutMs` defaults to `30000`
-- `apiKey` is optional in code, but required for hosted providers unless the
-  matching environment variable is available
+- `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`
 
 ## Provider Contract
 
@@ -39,7 +45,7 @@ Each provider exposes immutable metadata:
 
 ```ts
 interface EmbeddingProviderMetadata {
-  name: "local" | "gemini" | "openai";
+  name: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
   model: string;
   dimensions: number;
   batch: {
@@ -78,9 +84,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.
 
-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
@@ -108,6 +114,63 @@ Notes:
 - batch metadata is `{ mode: "sequential" }`
 - the first run downloads 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
+
+## Cloudflare Workers AI
+
+Provider value: `cloudflare`
+
+Cloudflare is the recommended hosted provider for low-cost Markdown search.
+It uses Workers AI `@cf/baai/bge-m3` through Cloudflare's OpenAI-compatible
+embeddings endpoint.
+
+```ts
+embeddingOptions: {
+  provider: "cloudflare",
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+  apiToken: process.env.CLOUDFLARE_API_TOKEN,
+}
+```
+
+Behavior:
+
+- if `accountId` is omitted, the library reads `CLOUDFLARE_ACCOUNT_ID`
+- if `apiToken` is omitted, the library reads `CLOUDFLARE_API_TOKEN`
+- blank Cloudflare credentials are treated as missing
+- `@cf/baai/bge-m3` returns 1024 dimensions
+- metadata reports `@cf/baai/bge-m3` and 1024 dimensions without requiring
+  credentials
+- batch metadata is `{ mode: "native" }`
+- response items are reordered by provider-supplied index before being returned
+- 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
 
@@ -156,7 +219,9 @@ Behavior:
 
 ## Dimension Guidelines
 
-- `768` is the easiest cross-provider target in the current implementation
+- `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
 - OpenAI can be used at 1536 or 3072, or another supported OpenAI dimension

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,6 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libsql-search",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "Semantic search for static sites using libSQL/Turso with multi-provider embeddings",
   "type": "module",
   "packageManager": "pnpm@10.34.5",