libsql-search 0.6.0 → 0.7.0

package/README.md

@@ -23,7 +23,8 @@ Use it when you want:
 - 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`
+  `text-embedding-3-large`; self-hosted OpenAI-compatible endpoints are also
+  available for TEI and similar trusted deployments
 - npm distribution plus JSR publishing
 
 ## Install

package/dist/index.cjs

@@ -5,6 +5,7 @@ var path = require('path');
 var matter = require('gray-matter');
 
 const OPENAI_DEFAULT_DIMENSIONS = 768;
+const OPENAI_COMPATIBLE_DEFAULT_BATCH_SIZE = 32;
 const LOCAL_DIMENSIONS = 384;
 const DEFAULT_MAX_LENGTH = 8e3;
 const DEFAULT_TIMEOUT_MS = 3e4;
@@ -111,6 +112,7 @@ function resolveProviderName(provider) {
     case "openai":
     case "mistral":
     case "cloudflare":
+    case "openai-compatible":
       return provider ?? "local";
     default:
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
@@ -135,6 +137,13 @@ function getOptionalTrimmedCredential(value) {
   const trimmed = value?.trim();
   return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
 }
+function getRequiredTrimmedString(value, optionName) {
+  const trimmed = getOptionalTrimmedCredential(value);
+  if (!trimmed) {
+    throw new Error(`Invalid ${optionName}: expected a non-empty string`);
+  }
+  return trimmed;
+}
 function hasOwnProperty(value, property) {
   return Object.prototype.hasOwnProperty.call(value, property);
 }
@@ -295,7 +304,27 @@ async function embedSequentially(provider, operation, texts, signal, embedOne) {
   }
   return results;
 }
-function createProviderMetadata(provider, dimensions) {
+function normalizeOpenAICompatibleEmbeddingsUrl(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error("Invalid baseUrl: expected an absolute http or https URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("Invalid baseUrl: expected an absolute http or https URL");
+  }
+  if (url.username || url.password) {
+    throw new Error("Invalid baseUrl: URL credentials are not allowed");
+  }
+  if (url.search || url.hash) {
+    throw new Error("Invalid baseUrl: query strings and fragments are not allowed");
+  }
+  const path = url.pathname.replace(/\/+$/, "");
+  url.pathname = path.endsWith("/embeddings") ? path : `${path}/embeddings`;
+  return url.toString();
+}
+function createProviderMetadata(provider, dimensions, model) {
   switch (provider) {
     case "local":
       return Object.freeze({
@@ -332,6 +361,13 @@ function createProviderMetadata(provider, dimensions) {
         dimensions: CLOUDFLARE_DIMENSIONS,
         batch: Object.freeze({ mode: "native" })
       });
+    case "openai-compatible":
+      return Object.freeze({
+        name: "openai-compatible",
+        model: getRequiredTrimmedString(model, "model"),
+        dimensions,
+        batch: Object.freeze({ mode: "native" })
+      });
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
@@ -372,6 +408,12 @@ function getEffectiveDimensions(provider, dimensions) {
     }
     return CLOUDFLARE_DIMENSIONS;
   }
+  if (provider === "openai-compatible") {
+    if (dimensions === void 0) {
+      throw new Error("Invalid dimensions: expected a positive integer");
+    }
+    return getPositiveInteger(dimensions, "dimensions");
+  }
   return getPositiveInteger(dimensions ?? OPENAI_DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
@@ -382,6 +424,13 @@ function assertBatchSize(metadata, count) {
     );
   }
 }
+function chunkTexts(texts, batchSize) {
+  const chunks = [];
+  for (let index = 0; index < texts.length; index += batchSize) {
+    chunks.push(texts.slice(index, index + batchSize));
+  }
+  return chunks;
+}
 function createEmbeddingBatchResult(metadata, intent, embeddings) {
   return Object.freeze({
     embeddings,
@@ -482,18 +531,23 @@ async function requestOpenAICompatibleEmbeddings(request) {
   if (request.encodingFormat !== void 0) {
     body.encoding_format = request.encodingFormat;
   }
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (request.apiKey !== void 0) {
+    headers.Authorization = `Bearer ${request.apiKey}`;
+  }
   const response = await fetch(request.endpoint, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${request.apiKey}`
-    },
+    headers,
     signal: request.signal,
-    body: JSON.stringify(body)
+    body: JSON.stringify(body),
+    ...request.redirect ? { redirect: request.redirect } : {}
   });
   if (!response.ok) {
-    const requestId = getSafeResponseHeader(response, "x-request-id");
-    const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
+    const statusHeader = request.statusHeader ?? { name: "x-request-id", label: "request" };
+    const statusHeaderValue = getSafeResponseHeader(response, statusHeader.name);
+    const context = statusHeaderValue ? ` status ${response.status}, ${statusHeader.label} ${statusHeaderValue}` : ` status ${response.status}`;
     throw new Error(context);
   }
   const data = await response.json();
@@ -517,13 +571,13 @@ async function requestOpenAICompatibleEmbeddings(request) {
     return parsed;
   });
 }
-class OpenAIEmbeddingProvider {
+class OpenAICompatibleEmbeddingProvider {
   metadata;
-  #apiKey;
   #timeoutMs;
-  constructor(metadata, apiKey, timeoutMs) {
+  #profile;
+  constructor(metadata, profile, timeoutMs) {
     this.metadata = metadata;
-    this.#apiKey = apiKey;
+    this.#profile = profile;
     this.#timeoutMs = timeoutMs;
   }
   async embed(texts, options = {}) {
@@ -533,131 +587,44 @@ class OpenAIEmbeddingProvider {
     }
     assertBatchSize(this.metadata, texts.length);
     const items = await withTimeout(
-      "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",
+      this.#profile.provider,
       "API request",
       this.#timeoutMs,
       async (signal) => {
-        const response = await fetch(endpoint, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.#apiToken}`
-          },
-          signal,
-          body: JSON.stringify({
-            model: this.metadata.model,
-            input: texts
-          })
-        });
-        if (!response.ok) {
-          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("Cloudflare response did not include a data array");
+        const batches = this.#profile.batchSize === void 0 ? [texts] : chunkTexts(texts, this.#profile.batchSize);
+        const results = [];
+        for (const batch of batches) {
+          throwIfAborted(this.#profile.provider, "API request", signal);
+          const batchItems = await requestOpenAICompatibleEmbeddings({
+            responseLabel: this.#profile.responseLabel,
+            endpoint: this.#profile.endpoint,
+            ...this.#profile.apiKey !== void 0 ? { apiKey: this.#profile.apiKey } : {},
+            model: this.#profile.model,
+            texts: batch,
+            signal,
+            ...this.#profile.includeDimensions ? { dimensions: this.#profile.dimensions } : {},
+            ...this.#profile.encodingFormat ? { encodingFormat: this.#profile.encodingFormat } : {},
+            ...this.#profile.requireIndex !== void 0 ? { requireIndex: this.#profile.requireIndex } : {},
+            ...this.#profile.redirect ? { redirect: this.#profile.redirect } : {},
+            ...this.#profile.statusHeader ? { statusHeader: this.#profile.statusHeader } : {}
+          });
+          results.push(...validateEmbeddingBatch(
+            batchItems,
+            batch.length,
+            this.metadata.dimensions,
+            this.#profile.provider
+          ));
+          throwIfAborted(this.#profile.provider, "API request", signal);
         }
-        return data.data.map((item) => {
-          const typed = item;
-          const embedding = typed.embedding;
-          if (!Array.isArray(embedding)) {
-            throw new Error("Cloudflare response item did not include an embedding array");
-          }
-          const parsed = { embedding };
-          if (hasOwnProperty(typed, "index")) {
-            parsed.index = typed.index;
-          }
-          return parsed;
-        });
+        return results;
       },
       options.signal,
-      [this.#apiToken, this.#accountId, encodeURIComponent(this.#accountId)]
+      this.#profile.exactSecrets ?? []
     );
     return createEmbeddingBatchResult(
       this.metadata,
       intent,
-      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "cloudflare")
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, this.#profile.provider)
     );
   }
 }
@@ -682,7 +649,16 @@ function createEmbeddingProvider(options = {}) {
       if (!key) {
         throw new Error("OPENAI_API_KEY is required for OpenAI embeddings");
       }
-      return new OpenAIEmbeddingProvider(metadata, key, timeoutMs);
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "openai",
+        responseLabel: "OpenAI",
+        endpoint: OPENAI_EMBEDDINGS_URL,
+        apiKey: key,
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        includeDimensions: true,
+        exactSecrets: [key]
+      }, timeoutMs);
     }
     case "mistral": {
       const key = getOptionalTrimmedCredential(
@@ -691,7 +667,17 @@ function createEmbeddingProvider(options = {}) {
       if (!key) {
         throw new Error("MISTRAL_API_KEY is required for Mistral embeddings");
       }
-      return new MistralEmbeddingProvider(metadata, key, timeoutMs);
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "mistral",
+        responseLabel: "Mistral",
+        endpoint: MISTRAL_EMBEDDINGS_URL,
+        apiKey: key,
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        encodingFormat: "float",
+        requireIndex: true,
+        exactSecrets: [key]
+      }, timeoutMs);
     }
     case "cloudflare": {
       const accountId = getOptionalTrimmedCredential(
@@ -706,13 +692,56 @@ function createEmbeddingProvider(options = {}) {
       if (!apiToken) {
         throw new Error("CLOUDFLARE_API_TOKEN is required for Cloudflare embeddings");
       }
-      return new CloudflareEmbeddingProvider(metadata, accountId, apiToken, timeoutMs);
+      const endpoint = createCloudflareEmbeddingsUrl(accountId);
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "cloudflare",
+        responseLabel: "Cloudflare",
+        endpoint,
+        apiKey: apiToken,
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        statusHeader: { name: "cf-ray", label: "cf-ray" },
+        exactSecrets: [apiToken, accountId, encodeURIComponent(accountId), endpoint]
+      }, timeoutMs);
+    }
+    case "openai-compatible": {
+      const baseUrl = getRequiredTrimmedString(options.baseUrl, "baseUrl");
+      const endpoint = normalizeOpenAICompatibleEmbeddingsUrl(baseUrl);
+      const apiKey = getOptionalTrimmedCredential(options.apiKey);
+      const batchSize = getPositiveInteger(
+        options.batchSize ?? OPENAI_COMPATIBLE_DEFAULT_BATCH_SIZE,
+        "batchSize"
+      );
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "openai-compatible",
+        responseLabel: "OpenAI-compatible",
+        endpoint,
+        ...apiKey ? { apiKey } : {},
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        includeDimensions: true,
+        encodingFormat: "float",
+        requireIndex: true,
+        redirect: "error",
+        batchSize,
+        exactSecrets: [
+          ...apiKey ? [apiKey] : [],
+          baseUrl,
+          endpoint
+        ]
+      }, timeoutMs);
     }
   }
 }
 function getEmbeddingProviderMetadata(options = {}) {
   const provider = resolveProviderName(options.provider);
-  return createProviderMetadata(provider, getEffectiveDimensions(provider, options.dimensions));
+  if (provider === "openai-compatible") {
+    normalizeOpenAICompatibleEmbeddingsUrl(getRequiredTrimmedString(options.baseUrl, "baseUrl"));
+    if (options.batchSize !== void 0) {
+      getPositiveInteger(options.batchSize, "batchSize");
+    }
+  }
+  return createProviderMetadata(provider, getEffectiveDimensions(provider, options.dimensions), options.model);
 }
 async function generateEmbeddings(texts, options = {}) {
   const maxLength = getPositiveInteger(options.maxLength ?? DEFAULT_MAX_LENGTH, "maxLength");

package/dist/index.d.ts

@@ -2,9 +2,10 @@ import { Client } from '@libsql/client';
 
 /**
  * Multi-provider embedding generation
- * Supports local Hugging Face Transformers, Gemini, OpenAI, Mistral, and Cloudflare Workers AI
+ * Supports local Hugging Face Transformers, Gemini, OpenAI, Mistral,
+ * Cloudflare Workers AI, and custom OpenAI-compatible endpoints
  */
-type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'mistral' | 'cloudflare';
+type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'mistral' | 'cloudflare' | 'openai-compatible';
 type EmbeddingIntent = 'document' | 'query';
 type EmbeddingBatchMode = 'native' | 'sequential';
 interface EmbeddingBatchBehavior {
@@ -37,6 +38,9 @@ interface EmbeddingOptions {
     apiKey?: string;
     accountId?: string;
     apiToken?: string;
+    baseUrl?: string;
+    model?: string;
+    batchSize?: number;
     dimensions?: number;
     maxLength?: number;
     intent?: EmbeddingIntent;

package/dist/index.esm.js

@@ -3,6 +3,7 @@ import { join, extname, relative, dirname } from 'path';
 import matter from 'gray-matter';
 
 const OPENAI_DEFAULT_DIMENSIONS = 768;
+const OPENAI_COMPATIBLE_DEFAULT_BATCH_SIZE = 32;
 const LOCAL_DIMENSIONS = 384;
 const DEFAULT_MAX_LENGTH = 8e3;
 const DEFAULT_TIMEOUT_MS = 3e4;
@@ -109,6 +110,7 @@ function resolveProviderName(provider) {
     case "openai":
     case "mistral":
     case "cloudflare":
+    case "openai-compatible":
       return provider ?? "local";
     default:
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
@@ -133,6 +135,13 @@ function getOptionalTrimmedCredential(value) {
   const trimmed = value?.trim();
   return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
 }
+function getRequiredTrimmedString(value, optionName) {
+  const trimmed = getOptionalTrimmedCredential(value);
+  if (!trimmed) {
+    throw new Error(`Invalid ${optionName}: expected a non-empty string`);
+  }
+  return trimmed;
+}
 function hasOwnProperty(value, property) {
   return Object.prototype.hasOwnProperty.call(value, property);
 }
@@ -293,7 +302,27 @@ async function embedSequentially(provider, operation, texts, signal, embedOne) {
   }
   return results;
 }
-function createProviderMetadata(provider, dimensions) {
+function normalizeOpenAICompatibleEmbeddingsUrl(baseUrl) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    throw new Error("Invalid baseUrl: expected an absolute http or https URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("Invalid baseUrl: expected an absolute http or https URL");
+  }
+  if (url.username || url.password) {
+    throw new Error("Invalid baseUrl: URL credentials are not allowed");
+  }
+  if (url.search || url.hash) {
+    throw new Error("Invalid baseUrl: query strings and fragments are not allowed");
+  }
+  const path = url.pathname.replace(/\/+$/, "");
+  url.pathname = path.endsWith("/embeddings") ? path : `${path}/embeddings`;
+  return url.toString();
+}
+function createProviderMetadata(provider, dimensions, model) {
   switch (provider) {
     case "local":
       return Object.freeze({
@@ -330,6 +359,13 @@ function createProviderMetadata(provider, dimensions) {
         dimensions: CLOUDFLARE_DIMENSIONS,
         batch: Object.freeze({ mode: "native" })
       });
+    case "openai-compatible":
+      return Object.freeze({
+        name: "openai-compatible",
+        model: getRequiredTrimmedString(model, "model"),
+        dimensions,
+        batch: Object.freeze({ mode: "native" })
+      });
   }
 }
 function getEffectiveDimensions(provider, dimensions) {
@@ -370,6 +406,12 @@ function getEffectiveDimensions(provider, dimensions) {
     }
     return CLOUDFLARE_DIMENSIONS;
   }
+  if (provider === "openai-compatible") {
+    if (dimensions === void 0) {
+      throw new Error("Invalid dimensions: expected a positive integer");
+    }
+    return getPositiveInteger(dimensions, "dimensions");
+  }
   return getPositiveInteger(dimensions ?? OPENAI_DEFAULT_DIMENSIONS, "dimensions");
 }
 function assertBatchSize(metadata, count) {
@@ -380,6 +422,13 @@ function assertBatchSize(metadata, count) {
     );
   }
 }
+function chunkTexts(texts, batchSize) {
+  const chunks = [];
+  for (let index = 0; index < texts.length; index += batchSize) {
+    chunks.push(texts.slice(index, index + batchSize));
+  }
+  return chunks;
+}
 function createEmbeddingBatchResult(metadata, intent, embeddings) {
   return Object.freeze({
     embeddings,
@@ -480,18 +529,23 @@ async function requestOpenAICompatibleEmbeddings(request) {
   if (request.encodingFormat !== void 0) {
     body.encoding_format = request.encodingFormat;
   }
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (request.apiKey !== void 0) {
+    headers.Authorization = `Bearer ${request.apiKey}`;
+  }
   const response = await fetch(request.endpoint, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${request.apiKey}`
-    },
+    headers,
     signal: request.signal,
-    body: JSON.stringify(body)
+    body: JSON.stringify(body),
+    ...request.redirect ? { redirect: request.redirect } : {}
   });
   if (!response.ok) {
-    const requestId = getSafeResponseHeader(response, "x-request-id");
-    const context = requestId ? ` status ${response.status}, request ${requestId}` : ` status ${response.status}`;
+    const statusHeader = request.statusHeader ?? { name: "x-request-id", label: "request" };
+    const statusHeaderValue = getSafeResponseHeader(response, statusHeader.name);
+    const context = statusHeaderValue ? ` status ${response.status}, ${statusHeader.label} ${statusHeaderValue}` : ` status ${response.status}`;
     throw new Error(context);
   }
   const data = await response.json();
@@ -515,13 +569,13 @@ async function requestOpenAICompatibleEmbeddings(request) {
     return parsed;
   });
 }
-class OpenAIEmbeddingProvider {
+class OpenAICompatibleEmbeddingProvider {
   metadata;
-  #apiKey;
   #timeoutMs;
-  constructor(metadata, apiKey, timeoutMs) {
+  #profile;
+  constructor(metadata, profile, timeoutMs) {
     this.metadata = metadata;
-    this.#apiKey = apiKey;
+    this.#profile = profile;
     this.#timeoutMs = timeoutMs;
   }
   async embed(texts, options = {}) {
@@ -531,131 +585,44 @@ class OpenAIEmbeddingProvider {
     }
     assertBatchSize(this.metadata, texts.length);
     const items = await withTimeout(
-      "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",
+      this.#profile.provider,
       "API request",
       this.#timeoutMs,
       async (signal) => {
-        const response = await fetch(endpoint, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${this.#apiToken}`
-          },
-          signal,
-          body: JSON.stringify({
-            model: this.metadata.model,
-            input: texts
-          })
-        });
-        if (!response.ok) {
-          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("Cloudflare response did not include a data array");
+        const batches = this.#profile.batchSize === void 0 ? [texts] : chunkTexts(texts, this.#profile.batchSize);
+        const results = [];
+        for (const batch of batches) {
+          throwIfAborted(this.#profile.provider, "API request", signal);
+          const batchItems = await requestOpenAICompatibleEmbeddings({
+            responseLabel: this.#profile.responseLabel,
+            endpoint: this.#profile.endpoint,
+            ...this.#profile.apiKey !== void 0 ? { apiKey: this.#profile.apiKey } : {},
+            model: this.#profile.model,
+            texts: batch,
+            signal,
+            ...this.#profile.includeDimensions ? { dimensions: this.#profile.dimensions } : {},
+            ...this.#profile.encodingFormat ? { encodingFormat: this.#profile.encodingFormat } : {},
+            ...this.#profile.requireIndex !== void 0 ? { requireIndex: this.#profile.requireIndex } : {},
+            ...this.#profile.redirect ? { redirect: this.#profile.redirect } : {},
+            ...this.#profile.statusHeader ? { statusHeader: this.#profile.statusHeader } : {}
+          });
+          results.push(...validateEmbeddingBatch(
+            batchItems,
+            batch.length,
+            this.metadata.dimensions,
+            this.#profile.provider
+          ));
+          throwIfAborted(this.#profile.provider, "API request", signal);
         }
-        return data.data.map((item) => {
-          const typed = item;
-          const embedding = typed.embedding;
-          if (!Array.isArray(embedding)) {
-            throw new Error("Cloudflare response item did not include an embedding array");
-          }
-          const parsed = { embedding };
-          if (hasOwnProperty(typed, "index")) {
-            parsed.index = typed.index;
-          }
-          return parsed;
-        });
+        return results;
       },
       options.signal,
-      [this.#apiToken, this.#accountId, encodeURIComponent(this.#accountId)]
+      this.#profile.exactSecrets ?? []
     );
     return createEmbeddingBatchResult(
       this.metadata,
       intent,
-      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, "cloudflare")
+      validateEmbeddingBatch(items, texts.length, this.metadata.dimensions, this.#profile.provider)
     );
   }
 }
@@ -680,7 +647,16 @@ function createEmbeddingProvider(options = {}) {
       if (!key) {
         throw new Error("OPENAI_API_KEY is required for OpenAI embeddings");
       }
-      return new OpenAIEmbeddingProvider(metadata, key, timeoutMs);
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "openai",
+        responseLabel: "OpenAI",
+        endpoint: OPENAI_EMBEDDINGS_URL,
+        apiKey: key,
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        includeDimensions: true,
+        exactSecrets: [key]
+      }, timeoutMs);
     }
     case "mistral": {
       const key = getOptionalTrimmedCredential(
@@ -689,7 +665,17 @@ function createEmbeddingProvider(options = {}) {
       if (!key) {
         throw new Error("MISTRAL_API_KEY is required for Mistral embeddings");
       }
-      return new MistralEmbeddingProvider(metadata, key, timeoutMs);
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "mistral",
+        responseLabel: "Mistral",
+        endpoint: MISTRAL_EMBEDDINGS_URL,
+        apiKey: key,
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        encodingFormat: "float",
+        requireIndex: true,
+        exactSecrets: [key]
+      }, timeoutMs);
     }
     case "cloudflare": {
       const accountId = getOptionalTrimmedCredential(
@@ -704,13 +690,56 @@ function createEmbeddingProvider(options = {}) {
       if (!apiToken) {
         throw new Error("CLOUDFLARE_API_TOKEN is required for Cloudflare embeddings");
       }
-      return new CloudflareEmbeddingProvider(metadata, accountId, apiToken, timeoutMs);
+      const endpoint = createCloudflareEmbeddingsUrl(accountId);
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "cloudflare",
+        responseLabel: "Cloudflare",
+        endpoint,
+        apiKey: apiToken,
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        statusHeader: { name: "cf-ray", label: "cf-ray" },
+        exactSecrets: [apiToken, accountId, encodeURIComponent(accountId), endpoint]
+      }, timeoutMs);
+    }
+    case "openai-compatible": {
+      const baseUrl = getRequiredTrimmedString(options.baseUrl, "baseUrl");
+      const endpoint = normalizeOpenAICompatibleEmbeddingsUrl(baseUrl);
+      const apiKey = getOptionalTrimmedCredential(options.apiKey);
+      const batchSize = getPositiveInteger(
+        options.batchSize ?? OPENAI_COMPATIBLE_DEFAULT_BATCH_SIZE,
+        "batchSize"
+      );
+      return new OpenAICompatibleEmbeddingProvider(metadata, {
+        provider: "openai-compatible",
+        responseLabel: "OpenAI-compatible",
+        endpoint,
+        ...apiKey ? { apiKey } : {},
+        model: metadata.model,
+        dimensions: metadata.dimensions,
+        includeDimensions: true,
+        encodingFormat: "float",
+        requireIndex: true,
+        redirect: "error",
+        batchSize,
+        exactSecrets: [
+          ...apiKey ? [apiKey] : [],
+          baseUrl,
+          endpoint
+        ]
+      }, timeoutMs);
     }
   }
 }
 function getEmbeddingProviderMetadata(options = {}) {
   const provider = resolveProviderName(options.provider);
-  return createProviderMetadata(provider, getEffectiveDimensions(provider, options.dimensions));
+  if (provider === "openai-compatible") {
+    normalizeOpenAICompatibleEmbeddingsUrl(getRequiredTrimmedString(options.baseUrl, "baseUrl"));
+    if (options.batchSize !== void 0) {
+      getPositiveInteger(options.batchSize, "batchSize");
+    }
+  }
+  return createProviderMetadata(provider, getEffectiveDimensions(provider, options.dimensions), options.model);
 }
 async function generateEmbeddings(texts, options = {}) {
   const maxLength = getPositiveInteger(options.maxLength ?? DEFAULT_MAX_LENGTH, "maxLength");

package/docs/API.md

@@ -246,7 +246,13 @@ Provider clients return:
 ```ts
 interface EmbeddingBatchResult {
   embeddings: number[][];
-  provider: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
+  provider:
+    | "local"
+    | "cloudflare"
+    | "mistral"
+    | "gemini"
+    | "openai"
+    | "openai-compatible";
   model: string;
   dimensions: number;
   intent: "document" | "query";
@@ -262,10 +268,19 @@ cardinality, dimensions, finite numeric values, and indexed batch ordering.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
+  provider?:
+    | "local"
+    | "cloudflare"
+    | "mistral"
+    | "gemini"
+    | "openai"
+    | "openai-compatible";
   apiKey?: string;
   accountId?: string;
   apiToken?: string;
+  baseUrl?: string;
+  model?: string;
+  batchSize?: number;
   dimensions?: number;
   maxLength?: number;
   intent?: "document" | "query";
@@ -279,6 +294,13 @@ interface EmbeddingOptions {
 Cloudflare uses `accountId` and `apiToken`, which fall back to
 `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`.
 
+For `provider: "openai-compatible"`, callers must pass `baseUrl`, `model`, and
+`dimensions`. `apiKey` is optional and is used only when explicitly provided;
+the provider never reads `OPENAI_API_KEY`. `batchSize` controls the maximum
+items per outbound request and defaults to `32`. The endpoint is treated as
+trusted server-side configuration and should not be derived from untrusted
+request input.
+
 ### `padEmbedding(embedding, targetDimensions)`
 
 Pads or truncates an embedding array to the requested length.

package/docs/INTEGRATIONS.md

@@ -132,6 +132,7 @@ const embeddingProvider =
     | "mistral"
     | "gemini"
     | "openai"
+    | "openai-compatible"
     | undefined;
 
 const dimensionsByProvider = {
@@ -142,7 +143,10 @@ const dimensionsByProvider = {
   openai: 1536,
 } as const;
 
-const embeddingDimensions = dimensionsByProvider[embeddingProvider ?? "local"];
+const embeddingDimensions =
+  embeddingProvider === "openai-compatible"
+    ? Number(process.env.EMBEDDING_DIMENSIONS)
+    : dimensionsByProvider[embeddingProvider ?? "local"];
 
 await createTable(client, "articles", embeddingDimensions);
 
@@ -151,6 +155,8 @@ await indexContent({
   contentPath: "./content",
   embeddingOptions: {
     provider: embeddingProvider,
+    baseUrl: process.env.EMBEDDING_BASE_URL,
+    model: process.env.EMBEDDING_MODEL,
     dimensions: embeddingDimensions,
   },
 });
@@ -158,3 +164,9 @@ await indexContent({
 
 Pair this with your framework build command so indexed content and deployed code
 stay in sync.
+
+When you use `openai-compatible`, keep `EMBEDDING_BASE_URL` as trusted
+server-side configuration, not user request input. Recreate the vector table or
+rebuild into a separate table whenever the provider, endpoint, model, or
+dimension count changes; stored vectors and query vectors must come from the
+same embedding space.

package/docs/PROVIDERS.md

@@ -1,12 +1,13 @@
 # Embedding Providers
 
-`libsql-search` currently supports five embedding providers:
+`libsql-search` currently supports six embedding providers:
 
 - `local`
 - `cloudflare`
 - `mistral`
 - `gemini`
 - `openai`
+- `openai-compatible`
 
 Use the same provider and dimensions for both indexing and querying. A mismatch
 between stored vectors and query vectors will break search quality or fail at
@@ -16,10 +17,19 @@ query time.
 
 ```ts
 interface EmbeddingOptions {
-  provider?: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
+  provider?:
+    | "local"
+    | "cloudflare"
+    | "mistral"
+    | "gemini"
+    | "openai"
+    | "openai-compatible";
   apiKey?: string;
   accountId?: string;
   apiToken?: string;
+  baseUrl?: string;
+  model?: string;
+  batchSize?: number;
   dimensions?: number;
   maxLength?: number;
   intent?: "document" | "query";
@@ -37,9 +47,12 @@ interface EmbeddingOptions {
   `"document"` and search defaults to `"query"` unless explicitly set
 - `timeoutMs` defaults to `30000`
 - `apiKey` is used by Mistral, Gemini, and OpenAI and falls back to
-  `MISTRAL_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY`
+  `MISTRAL_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY`. For
+  `openai-compatible`, `apiKey` is optional and never falls back to
+  `OPENAI_API_KEY`.
 - `accountId` and `apiToken` are used by Cloudflare and fall back to
   `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`
+- `baseUrl`, `model`, and `batchSize` are used by `openai-compatible`
 
 ## Provider Contract
 
@@ -47,7 +60,13 @@ Each provider exposes immutable metadata:
 
 ```ts
 interface EmbeddingProviderMetadata {
-  name: "local" | "cloudflare" | "mistral" | "gemini" | "openai";
+  name:
+    | "local"
+    | "cloudflare"
+    | "mistral"
+    | "gemini"
+    | "openai"
+    | "openai-compatible";
   model: string;
   dimensions: number;
   batch: {
@@ -229,6 +248,80 @@ Behavior:
 - batch metadata is `{ mode: "native", maxSize: 2048 }`
 - use the same dimension count in `createTable()`
 
+## OpenAI-Compatible Endpoints
+
+Provider value: `openai-compatible`
+
+Use this provider for trusted OpenAI-compatible embedding services such as
+Hugging Face Text Embeddings Inference (TEI) or an internal gateway. This is an
+optional escape hatch; `local` remains the default offline provider, and the
+named hosted providers above are still preferred when their fixed adapters fit.
+
+```ts
+embeddingOptions: {
+  provider: "openai-compatible",
+  baseUrl: "http://localhost:8080/v1",
+  model: "BAAI/bge-large-en-v1.5",
+  dimensions: 1024,
+  batchSize: 32,
+}
+```
+
+If your endpoint requires bearer auth, pass `apiKey` explicitly:
+
+```ts
+embeddingOptions: {
+  provider: "openai-compatible",
+  baseUrl: "https://embeddings.example.com/v1",
+  apiKey: process.env.EMBEDDINGS_API_KEY,
+  model: "BAAI/bge-large-en-v1.5",
+  dimensions: 1024,
+}
+```
+
+Behavior:
+
+- `baseUrl`, `model`, and `dimensions` are required
+- `baseUrl` is the API base, such as `http://localhost:8080/v1`; the library
+  sends requests to `/embeddings` below that base
+- a base URL that already ends in `/embeddings` is used as-is
+- only absolute `http` and `https` URLs are accepted
+- URL usernames, passwords, query strings, and fragments are rejected
+- `apiKey` is optional; blank keys are ignored and no `Authorization` header is
+  sent
+- `OPENAI_API_KEY` is never read for this provider
+- `batchSize` defaults to `32`, matching TEI's conservative client batch size;
+  larger input arrays are split into sequential outbound requests and returned
+  in the original input order
+- requests send `{ input, model, dimensions, encoding_format: "float" }`
+- responses must use the standard OpenAI embeddings shape with indexed
+  `data[]` items; each response chunk must include unique contiguous indices
+- batch metadata is `{ mode: "native" }`; the internal outbound chunk size is
+  not reported as `batch.maxSize`
+
+Security boundary:
+
+- treat `baseUrl` as trusted server-side configuration only
+- never pass user-supplied request values directly into `baseUrl`
+- use HTTPS for remote endpoints
+- credentials are not sent across redirects
+- non-2xx response bodies are not read, and errors avoid echoing API keys or
+  configured endpoint URLs
+
+TEI exposes an OpenAI-compatible base at `/v1`, so a local TEI server usually
+uses:
+
+```ts
+embeddingOptions: {
+  provider: "openai-compatible",
+  baseUrl: "http://localhost:8080/v1",
+  model: "BAAI/bge-large-en-v1.5",
+  dimensions: 1024,
+}
+```
+
+This library does not call TEI's native `/embed` endpoint.
+
 ## Dimension Guidelines
 
 - `local` is fixed at `384`
@@ -238,9 +331,12 @@ Behavior:
   `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
+- `openai-compatible` requires you to set the dimension count that your
+  endpoint/model actually returns
 
-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.
+If you switch provider, endpoint, model, 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`,

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, Cloudflare, Mistral, Gemini, and
-  OpenAI embedding options, dimensions, and API key behavior
+- [Provider guide](./PROVIDERS.md): local, hosted, and OpenAI-compatible
+  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/package.json

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