libsql-search 0.5.0 → 0.7.0

package/dist/index.esm.js

@@ -2,7 +2,9 @@ import { readdir, readFile } from 'fs/promises';
 import { join, extname, relative, dirname } from 'path';
 import matter from 'gray-matter';
 
-const DEFAULT_DIMENSIONS = 768;
+const OPENAI_DEFAULT_DIMENSIONS = 768;
+const OPENAI_COMPATIBLE_DEFAULT_BATCH_SIZE = 32;
+const LOCAL_DIMENSIONS = 384;
 const DEFAULT_MAX_LENGTH = 8e3;
 const DEFAULT_TIMEOUT_MS = 3e4;
 const LOCAL_MODEL = "Xenova/all-MiniLM-L6-v2";
@@ -31,17 +33,66 @@ function getEnvironmentVariable(name) {
     return void 0;
   }
 }
-async function getLocalEmbeddingModel(modelName) {
+function deletePendingLocalModelCache(modelName, entry) {
+  if (!entry.settled && entry.waiters === 0 && localModelCacheByModel.get(modelName) === entry) {
+    localModelCacheByModel.delete(modelName);
+  }
+}
+async function getLocalEmbeddingModel(modelName, signal) {
   const cached = localModelCacheByModel.get(modelName);
-  if (cached?.model) {
-    return cached.model;
+  if (cached) {
+    cached.waiters++;
+    try {
+      return await waitForLocalEmbeddingModel(modelName, cached, signal);
+    } finally {
+      cached.waiters--;
+      deletePendingLocalModelCache(modelName, cached);
+    }
+  }
+  const modelPromise = (async () => {
+    console.log(`Loading local embedding model (${modelName})...`);
+    const { pipeline } = await import('@huggingface/transformers');
+    const model = await pipeline("feature-extraction", modelName);
+    console.log("Local model loaded successfully");
+    return model;
+  })();
+  const entry = {
+    promise: modelPromise,
+    settled: false,
+    waiters: 1
+  };
+  localModelCacheByModel.set(modelName, entry);
+  modelPromise.then(() => {
+    entry.settled = true;
+  }).catch(() => {
+    localModelCacheByModel.delete(modelName);
+  });
+  try {
+    return await waitForLocalEmbeddingModel(modelName, entry, signal);
+  } finally {
+    entry.waiters--;
+    deletePendingLocalModelCache(modelName, entry);
+  }
+}
+async function waitForLocalEmbeddingModel(modelName, entry, signal) {
+  if (signal.aborted) {
+    deletePendingLocalModelCache(modelName, entry);
+    throw providerError("local", "model inference was aborted");
+  }
+  let rejectAbort = () => {
+  };
+  const abortPromise = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const onAbort = () => {
+    rejectAbort(providerError("local", "model inference was aborted"));
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await Promise.race([entry.promise, abortPromise]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
   }
-  console.log(`Loading local embedding model (${modelName})...`);
-  const { pipeline } = await import('@xenova/transformers');
-  const model = await pipeline("feature-extraction", modelName);
-  localModelCacheByModel.set(modelName, { model });
-  console.log("Local model loaded successfully");
-  return model;
 }
 function getPositiveInteger(value, optionName) {
   if (!Number.isInteger(value) || value <= 0) {
@@ -59,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)}`);
@@ -83,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);
 }
@@ -243,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({
@@ -280,9 +359,25 @@ 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) {
+  if (provider === "local") {
+    if (dimensions !== void 0 && dimensions !== LOCAL_DIMENSIONS) {
+      throw providerError(
+        "local",
+        `${LOCAL_MODEL} returns ${LOCAL_DIMENSIONS} dimensions; received dimensions ${String(dimensions)}`
+      );
+    }
+    return LOCAL_DIMENSIONS;
+  }
   if (provider === "gemini") {
     const effectiveDimensions = dimensions ?? GEMINI_DIMENSIONS;
     if (!Number.isInteger(effectiveDimensions) || effectiveDimensions < GEMINI_MIN_DIMENSIONS || effectiveDimensions > GEMINI_MAX_DIMENSIONS) {
@@ -311,7 +406,13 @@ function getEffectiveDimensions(provider, dimensions) {
     }
     return CLOUDFLARE_DIMENSIONS;
   }
-  return getPositiveInteger(dimensions ?? DEFAULT_DIMENSIONS, "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) {
   if (metadata.batch.maxSize !== void 0 && count > metadata.batch.maxSize) {
@@ -321,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,
@@ -348,14 +456,13 @@ class LocalEmbeddingProvider {
       "model inference",
       this.#timeoutMs,
       async (signal) => {
-        const model = await getLocalEmbeddingModel(this.metadata.model);
+        const model = await getLocalEmbeddingModel(this.metadata.model, signal);
         return embedSequentially("local", "model inference", texts, signal, async (text) => {
           const output = await model(text, {
             pooling: "mean",
             normalize: true
           });
-          const embedding = Array.from(output.data);
-          return padEmbedding(embedding, this.metadata.dimensions);
+          return Array.from(output.data);
         });
       },
       options.signal
@@ -422,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();
@@ -457,92 +569,13 @@ async function requestOpenAICompatibleEmbeddings(request) {
     return parsed;
   });
 }
-class OpenAIEmbeddingProvider {
-  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(
-      "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 {
+class OpenAICompatibleEmbeddingProvider {
   metadata;
-  #accountId;
-  #apiToken;
   #timeoutMs;
-  constructor(metadata, accountId, apiToken, timeoutMs) {
+  #profile;
+  constructor(metadata, profile, timeoutMs) {
     this.metadata = metadata;
-    this.#accountId = accountId;
-    this.#apiToken = apiToken;
+    this.#profile = profile;
     this.#timeoutMs = timeoutMs;
   }
   async embed(texts, options = {}) {
@@ -551,53 +584,45 @@ class CloudflareEmbeddingProvider {
       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)
     );
   }
 }
@@ -622,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(
@@ -631,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(
@@ -646,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");
@@ -822,7 +909,7 @@ async function insertDocument(client, document, quotedTableName) {
     ]
   });
 }
-async function createTable(client, tableName = "articles", dimensions = 768) {
+async function createTable(client, tableName = "articles", dimensions = 384) {
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
   const vectorDimensions = normalizeVectorDimensions(dimensions);
   const quotedEmbeddingIndexName = quoteSqlIdentifier(`${tableName}_embedding_idx`, "embedding index name");

package/docs/API.md

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

package/docs/INDEXING.md

@@ -25,7 +25,6 @@ await indexContent({
   tableName: "articles",
   embeddingOptions: {
     provider: "local",
-    dimensions: 768,
   },
 });
 ```
@@ -34,6 +33,11 @@ That keeps the implementation simple, but it also means a failed rebuild can
 leave the index partially repopulated.
 
 Changing an embedding provider or dimension count requires a full re-embed.
+For existing local indexes created with the older padded-local behavior, create
+or recreate a 384-dimensional table before rebuilding. Those older local
+768-dimensional tables stored 384 model values followed by zero padding;
+`indexContent()` clears rows but does not change the table's `F32_BLOB` width.
+
 For Gemini specifically, indexes created with the retired `text-embedding-004`
 model must be rebuilt for `gemini-embedding-2` even when staying at 768
 dimensions, because the model and query/document formatting both changed. If
@@ -72,7 +76,7 @@ database calls or embedding generation.
 
 ## Runtime Notes
 
-- local embeddings may download a model on the first run
+- local embeddings may download and cache a model on the first run
 - Node users need `@libsql/client` installed alongside the package
 - the repository validates both the npm package build and `deno check`, but the
   indexing flow itself still depends on filesystem access

package/docs/INTEGRATIONS.md

@@ -26,7 +26,6 @@ export const POST: APIRoute = async ({ request }) => {
     limit,
     embeddingOptions: {
       provider: "local",
-      dimensions: 768,
     },
   });
 
@@ -79,7 +78,6 @@ export async function POST(request: NextRequest) {
     limit,
     embeddingOptions: {
       provider: "local",
-      dimensions: 768,
     },
   });
 
@@ -134,13 +132,21 @@ const embeddingProvider =
     | "mistral"
     | "gemini"
     | "openai"
+    | "openai-compatible"
     | undefined;
+
+const dimensionsByProvider = {
+  local: 384,
+  cloudflare: 1024,
+  mistral: 1024,
+  gemini: 3072,
+  openai: 1536,
+} as const;
+
 const embeddingDimensions =
-  embeddingProvider === "cloudflare" || embeddingProvider === "mistral"
-    ? 1024
-    : embeddingProvider === "gemini"
-      ? 3072
-    : 768;
+  embeddingProvider === "openai-compatible"
+    ? Number(process.env.EMBEDDING_DIMENSIONS)
+    : dimensionsByProvider[embeddingProvider ?? "local"];
 
 await createTable(client, "articles", embeddingDimensions);
 
@@ -149,6 +155,8 @@ await indexContent({
   contentPath: "./content",
   embeddingOptions: {
     provider: embeddingProvider,
+    baseUrl: process.env.EMBEDDING_BASE_URL,
+    model: process.env.EMBEDDING_MODEL,
     dimensions: embeddingDimensions,
   },
 });
@@ -156,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.