libsql-search 0.10.0 → 0.11.0

package/README.md

@@ -9,7 +9,7 @@
 
 Use it when you want:
 
-- one indexing/search API across local and hosted embedding providers
+- one indexing/search API across external embedding providers
 - direct control over vector dimensions, table names, and deployment shape
 - a lightweight library instead of a hosted search product
 
@@ -45,7 +45,7 @@ Note for `0.17.x`: the client no longer exports `./package.json`, so `require("@
 
 ## Quick Start
 
-This example uses the default local provider. Local embeddings run in-process after the initial model download and cache warmup; they are not automatically air-gapped.
+This example uses a separately deployed OpenAI-compatible embedding service. `libsql-search` never loads or hosts an embedding model in-process.
 
 ```ts
 import { createClient } from "@libsql/client";
@@ -56,25 +56,29 @@ const client = createClient({
   authToken: "your-auth-token",
 });
 
-await createTable(client, "articles_local_384", 384);
+const embeddingOptions = {
+  provider: "openai-compatible" as const,
+  baseUrl: process.env.EMBEDDING_BASE_URL!,
+  apiKey: process.env.EMBEDDING_API_KEY,
+  model: "bge-large-en-v1.5",
+  dimensions: 1024,
+};
+
+await createTable(client, "articles_bge_1024", 1024);
 
 await indexContent({
   client,
   contentPath: "./content",
-  tableName: "articles_local_384",
-  embeddingOptions: {
-    provider: "local",
-  },
+  tableName: "articles_bge_1024",
+  embeddingOptions,
 });
 
 const results = await search({
   client,
   query: "how do I deploy my docs site",
-  tableName: "articles_local_384",
+  tableName: "articles_bge_1024",
   limit: 5,
-  embeddingOptions: {
-    provider: "local",
-  },
+  embeddingOptions,
 });
 
 console.log(results.map((result) => ({
@@ -91,7 +95,7 @@ Important behavior:
 - `indexContent()` embeds every document before it touches the database, then replaces the table in one transaction, so a failed rebuild leaves the previous index intact.
 - `indexContent()` throws `IndexingError` when a file fails; pass `failurePolicy: "skip"` to rebuild from the remaining files.
 - `indexContent()` throws `IndexingError` when no source files are found; pass `allowEmptyIndex: true` to intentionally empty the index.
-- Hosted providers send indexed and queried text to external services and may incur provider charges.
+- Every provider sends indexed and queried text to an external service; review that service's privacy, retention, and pricing terms.
 
 ## Search Accuracy And Performance
 
@@ -103,10 +107,10 @@ Two options control the trade-off:
 
 ```ts
 // Widen the index probe to raise recall (default: max(limit * 4, 32))
-await search({ client, query, limit: 10, candidates: 200 });
+await search({ client, query, embeddingOptions, limit: 10, candidates: 200 });
 
 // Bypass the index entirely: exact, but linear in table size
-await search({ client, query, exact: true });
+await search({ client, query, embeddingOptions, exact: true });
 ```
 
 `exact: true` is the only way to guarantee exactness. Use it for small corpora, for correctness checks against the index path, and for tables that have no vector index.
@@ -117,7 +121,6 @@ Requirements: `vector_top_k()` and `libsql_vector_idx()` need a libSQL build wit
 
 Built-in providers:
 
-- `local` with `Xenova/all-MiniLM-L6-v2` at 384 dimensions
 - `cloudflare` with `@cf/baai/bge-m3` at 1024 dimensions
 - `mistral` with `mistral-embed` at 1024 dimensions
 - `gemini` with `gemini-embedding-2` at 128-3072 dimensions, default 3072

package/dist/index.cjs

@@ -6,10 +6,8 @@ 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;
-const LOCAL_MODEL = "Xenova/all-MiniLM-L6-v2";
 const GEMINI_MODEL = "gemini-embedding-2";
 const GEMINI_DIMENSIONS = 3072;
 const GEMINI_MIN_DIMENSIONS = 128;
@@ -22,7 +20,6 @@ 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;
   const nodeValue = runtime.process?.env?.[name];
@@ -35,67 +32,6 @@ function getEnvironmentVariable(name) {
     return void 0;
   }
 }
-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) {
-    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);
-  }
-}
 function getPositiveInteger(value, optionName) {
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`Invalid ${optionName}: expected a positive integer`);
@@ -106,15 +42,17 @@ function getTimeoutMs(value) {
   return getPositiveInteger(value ?? DEFAULT_TIMEOUT_MS, "timeoutMs");
 }
 function resolveProviderName(provider) {
-  switch (provider ?? "local") {
-    case "local":
+  switch (provider) {
     case "gemini":
     case "openai":
     case "mistral":
     case "cloudflare":
     case "openai-compatible":
-      return provider ?? "local";
+      return provider;
     default:
+      if (provider === void 0) {
+        throw new Error("Embedding provider is required");
+      }
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
   }
 }
@@ -326,13 +264,6 @@ function normalizeOpenAICompatibleEmbeddingsUrl(baseUrl) {
 }
 function createProviderMetadata(provider, dimensions, model) {
   switch (provider) {
-    case "local":
-      return Object.freeze({
-        name: "local",
-        model: LOCAL_MODEL,
-        dimensions,
-        batch: Object.freeze({ mode: "sequential" })
-      });
     case "gemini":
       return Object.freeze({
         name: "gemini",
@@ -371,15 +302,6 @@ function createProviderMetadata(provider, dimensions, model) {
   }
 }
 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) {
@@ -440,42 +362,6 @@ function createEmbeddingBatchResult(metadata, intent, embeddings) {
     intent
   });
 }
-class LocalEmbeddingProvider {
-  metadata;
-  #timeoutMs;
-  constructor(metadata, timeoutMs) {
-    this.metadata = metadata;
-    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 vectors = await withTimeout(
-      "local",
-      "model inference",
-      this.#timeoutMs,
-      async (signal) => {
-        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
-          });
-          return Array.from(output.data);
-        });
-      },
-      options.signal
-    );
-    return createEmbeddingBatchResult(
-      this.metadata,
-      intent,
-      validateEmbeddingBatch(vectors, texts.length, this.metadata.dimensions, "local")
-    );
-  }
-}
 class GeminiEmbeddingProvider {
   metadata;
   #apiKey;
@@ -628,13 +514,11 @@ class OpenAICompatibleEmbeddingProvider {
     );
   }
 }
-function createEmbeddingProvider(options = {}) {
+function createEmbeddingProvider(options) {
   const provider = resolveProviderName(options.provider);
   const metadata = getEmbeddingProviderMetadata(options);
   const timeoutMs = getTimeoutMs(options.timeoutMs);
   switch (provider) {
-    case "local":
-      return new LocalEmbeddingProvider(metadata, timeoutMs);
     case "gemini": {
       const key = getOptionalTrimmedCredential(
         options.apiKey ?? getEnvironmentVariable("GEMINI_API_KEY")
@@ -733,7 +617,7 @@ function createEmbeddingProvider(options = {}) {
     }
   }
 }
-function getEmbeddingProviderMetadata(options = {}) {
+function getEmbeddingProviderMetadata(options) {
   const provider = resolveProviderName(options.provider);
   if (provider === "openai-compatible") {
     normalizeOpenAICompatibleEmbeddingsUrl(getRequiredTrimmedString(options.baseUrl, "baseUrl"));
@@ -743,7 +627,7 @@ function getEmbeddingProviderMetadata(options = {}) {
   }
   return createProviderMetadata(provider, getEffectiveDimensions(provider, options.dimensions), options.model);
 }
-async function generateEmbeddings(texts, options = {}) {
+async function generateEmbeddings(texts, options) {
   const maxLength = getPositiveInteger(options.maxLength ?? DEFAULT_MAX_LENGTH, "maxLength");
   const intent = resolveIntent(options.intent);
   if (texts.length === 0) {
@@ -756,7 +640,7 @@ async function generateEmbeddings(texts, options = {}) {
   });
   return result.embeddings;
 }
-async function generateEmbedding(text, options = {}) {
+async function generateEmbedding(text, options) {
   const [embedding] = await generateEmbeddings([text], options);
   if (!embedding) {
     throw new Error("Embedding provider returned no embedding");
@@ -889,7 +773,7 @@ async function indexContent(options) {
   const {
     client,
     contentPath,
-    embeddingOptions = {},
+    embeddingOptions,
     fileExtensions = [".md", ".markdown"],
     exclude = ["node_modules", ".git", "dist", "build"],
     tableName = "articles",
@@ -899,6 +783,9 @@ async function indexContent(options) {
   } = options;
   const database = resolveDatabase(client);
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
+  if (embeddingOptions === void 0) {
+    throw new TypeError("embeddingOptions is required");
+  }
   let files;
   try {
     files = await findFiles(contentPath, contentPath, fileExtensions, exclude);
@@ -1017,11 +904,13 @@ async function buildDocument(file, embeddingOptions) {
     return { ok: false, stage: "parse", error: toError(error) };
   }
   let embedding;
+  let serializedEmbedding;
   try {
     embedding = await generateEmbedding(parsed.embeddingText, {
       ...embeddingOptions,
       intent: embeddingOptions.intent ?? "document"
     });
+    serializedEmbedding = JSON.stringify(embedding);
   } catch (error) {
     return { ok: false, stage: "embed", error: toError(error) };
   }
@@ -1035,6 +924,7 @@ async function buildDocument(file, embeddingOptions) {
       tags: parsed.tags,
       serializedTags: parsed.serializedTags,
       embedding,
+      serializedEmbedding,
       metadata: parsed.metadata
     }
   };
@@ -1119,7 +1009,7 @@ function createInsertStatement(document, quotedTableName) {
       document.content,
       document.folder,
       document.serializedTags,
-      JSON.stringify(document.embedding)
+      document.serializedEmbedding
     ]
   };
 }
@@ -1175,7 +1065,7 @@ async function search(options) {
     query,
     limit = 10,
     tableName = "articles",
-    embeddingOptions = {},
+    embeddingOptions,
     candidates,
     exact = false
   } = options;
@@ -1187,6 +1077,9 @@ async function search(options) {
     "embedding index name"
   );
   const candidateCount = normalizeSearchCandidates(candidates, resultLimit);
+  if (embeddingOptions === void 0) {
+    throw new TypeError("embeddingOptions is required");
+  }
   const queryEmbedding = await generateEmbedding(query, {
     ...embeddingOptions,
     intent: embeddingOptions.intent ?? "query"

package/dist/index.d.ts

@@ -2,10 +2,10 @@ import { Client } from '@libsql/client';
 
 /**
  * Multi-provider embedding generation
- * Supports local Hugging Face Transformers, Gemini, OpenAI, Mistral,
- * Cloudflare Workers AI, and custom OpenAI-compatible endpoints
+ * Supports Gemini, OpenAI, Mistral, Cloudflare Workers AI, and custom
+ * OpenAI-compatible endpoints.
  */
-type EmbeddingProvider = 'local' | 'gemini' | 'openai' | 'mistral' | 'cloudflare' | 'openai-compatible';
+type EmbeddingProvider = 'gemini' | 'openai' | 'mistral' | 'cloudflare' | 'openai-compatible';
 type EmbeddingIntent = 'document' | 'query';
 type EmbeddingBatchMode = 'native' | 'sequential';
 interface EmbeddingBatchBehavior {
@@ -34,7 +34,7 @@ interface EmbeddingBatchResult {
     intent: EmbeddingIntent;
 }
 interface EmbeddingOptions {
-    provider?: EmbeddingProvider;
+    provider: EmbeddingProvider;
     apiKey?: string;
     accountId?: string;
     apiToken?: string;
@@ -53,16 +53,16 @@ interface EmbeddingBatchItemResult {
 }
 type EmbeddingBatchItem = number[] | EmbeddingBatchItemResult;
 declare function validateEmbeddingBatch(items: EmbeddingBatchItem[], expectedCount: number, expectedDimensions: number, provider: EmbeddingProvider): number[][];
-declare function createEmbeddingProvider(options?: EmbeddingOptions): EmbeddingProviderClient;
-declare function getEmbeddingProviderMetadata(options?: EmbeddingOptions): EmbeddingProviderMetadata;
+declare function createEmbeddingProvider(options: EmbeddingOptions): EmbeddingProviderClient;
+declare function getEmbeddingProviderMetadata(options: EmbeddingOptions): EmbeddingProviderMetadata;
 /**
  * Generate embeddings using the specified provider.
  */
-declare function generateEmbeddings(texts: string[], options?: EmbeddingOptions): Promise<number[][]>;
+declare function generateEmbeddings(texts: string[], options: EmbeddingOptions): Promise<number[][]>;
 /**
  * Generate an embedding using the specified provider.
  */
-declare function generateEmbedding(text: string, options?: EmbeddingOptions): Promise<number[]>;
+declare function generateEmbedding(text: string, options: EmbeddingOptions): Promise<number[]>;
 /**
  * Pad or truncate embedding to target dimensions
  */
@@ -189,7 +189,7 @@ interface IndexerOptions {
      */
     client: DatabaseClient;
     contentPath: string;
-    embeddingOptions?: EmbeddingOptions;
+    embeddingOptions: EmbeddingOptions;
     fileExtensions?: string[];
     exclude?: string[];
     tableName?: string;
@@ -282,7 +282,7 @@ interface SearchOptions {
     query: string;
     limit?: number;
     tableName?: string;
-    embeddingOptions?: EmbeddingOptions;
+    embeddingOptions: EmbeddingOptions;
     /**
      * How many candidates to pull from the vector index before the exact
      * re-rank. Must be an integer from `limit` through {@link MAX_SEARCH_CANDIDATES}.

package/dist/index.esm.js

@@ -4,10 +4,8 @@ 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;
-const LOCAL_MODEL = "Xenova/all-MiniLM-L6-v2";
 const GEMINI_MODEL = "gemini-embedding-2";
 const GEMINI_DIMENSIONS = 3072;
 const GEMINI_MIN_DIMENSIONS = 128;
@@ -20,7 +18,6 @@ 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;
   const nodeValue = runtime.process?.env?.[name];
@@ -33,67 +30,6 @@ function getEnvironmentVariable(name) {
     return void 0;
   }
 }
-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) {
-    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);
-  }
-}
 function getPositiveInteger(value, optionName) {
   if (!Number.isInteger(value) || value <= 0) {
     throw new Error(`Invalid ${optionName}: expected a positive integer`);
@@ -104,15 +40,17 @@ function getTimeoutMs(value) {
   return getPositiveInteger(value ?? DEFAULT_TIMEOUT_MS, "timeoutMs");
 }
 function resolveProviderName(provider) {
-  switch (provider ?? "local") {
-    case "local":
+  switch (provider) {
     case "gemini":
     case "openai":
     case "mistral":
     case "cloudflare":
     case "openai-compatible":
-      return provider ?? "local";
+      return provider;
     default:
+      if (provider === void 0) {
+        throw new Error("Embedding provider is required");
+      }
       throw new Error(`Unknown embedding provider: ${String(provider)}`);
   }
 }
@@ -324,13 +262,6 @@ function normalizeOpenAICompatibleEmbeddingsUrl(baseUrl) {
 }
 function createProviderMetadata(provider, dimensions, model) {
   switch (provider) {
-    case "local":
-      return Object.freeze({
-        name: "local",
-        model: LOCAL_MODEL,
-        dimensions,
-        batch: Object.freeze({ mode: "sequential" })
-      });
     case "gemini":
       return Object.freeze({
         name: "gemini",
@@ -369,15 +300,6 @@ function createProviderMetadata(provider, dimensions, model) {
   }
 }
 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) {
@@ -438,42 +360,6 @@ function createEmbeddingBatchResult(metadata, intent, embeddings) {
     intent
   });
 }
-class LocalEmbeddingProvider {
-  metadata;
-  #timeoutMs;
-  constructor(metadata, timeoutMs) {
-    this.metadata = metadata;
-    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 vectors = await withTimeout(
-      "local",
-      "model inference",
-      this.#timeoutMs,
-      async (signal) => {
-        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
-          });
-          return Array.from(output.data);
-        });
-      },
-      options.signal
-    );
-    return createEmbeddingBatchResult(
-      this.metadata,
-      intent,
-      validateEmbeddingBatch(vectors, texts.length, this.metadata.dimensions, "local")
-    );
-  }
-}
 class GeminiEmbeddingProvider {
   metadata;
   #apiKey;
@@ -626,13 +512,11 @@ class OpenAICompatibleEmbeddingProvider {
     );
   }
 }
-function createEmbeddingProvider(options = {}) {
+function createEmbeddingProvider(options) {
   const provider = resolveProviderName(options.provider);
   const metadata = getEmbeddingProviderMetadata(options);
   const timeoutMs = getTimeoutMs(options.timeoutMs);
   switch (provider) {
-    case "local":
-      return new LocalEmbeddingProvider(metadata, timeoutMs);
     case "gemini": {
       const key = getOptionalTrimmedCredential(
         options.apiKey ?? getEnvironmentVariable("GEMINI_API_KEY")
@@ -731,7 +615,7 @@ function createEmbeddingProvider(options = {}) {
     }
   }
 }
-function getEmbeddingProviderMetadata(options = {}) {
+function getEmbeddingProviderMetadata(options) {
   const provider = resolveProviderName(options.provider);
   if (provider === "openai-compatible") {
     normalizeOpenAICompatibleEmbeddingsUrl(getRequiredTrimmedString(options.baseUrl, "baseUrl"));
@@ -741,7 +625,7 @@ function getEmbeddingProviderMetadata(options = {}) {
   }
   return createProviderMetadata(provider, getEffectiveDimensions(provider, options.dimensions), options.model);
 }
-async function generateEmbeddings(texts, options = {}) {
+async function generateEmbeddings(texts, options) {
   const maxLength = getPositiveInteger(options.maxLength ?? DEFAULT_MAX_LENGTH, "maxLength");
   const intent = resolveIntent(options.intent);
   if (texts.length === 0) {
@@ -754,7 +638,7 @@ async function generateEmbeddings(texts, options = {}) {
   });
   return result.embeddings;
 }
-async function generateEmbedding(text, options = {}) {
+async function generateEmbedding(text, options) {
   const [embedding] = await generateEmbeddings([text], options);
   if (!embedding) {
     throw new Error("Embedding provider returned no embedding");
@@ -887,7 +771,7 @@ async function indexContent(options) {
   const {
     client,
     contentPath,
-    embeddingOptions = {},
+    embeddingOptions,
     fileExtensions = [".md", ".markdown"],
     exclude = ["node_modules", ".git", "dist", "build"],
     tableName = "articles",
@@ -897,6 +781,9 @@ async function indexContent(options) {
   } = options;
   const database = resolveDatabase(client);
   const quotedTableName = quoteSqlIdentifier(tableName, "tableName");
+  if (embeddingOptions === void 0) {
+    throw new TypeError("embeddingOptions is required");
+  }
   let files;
   try {
     files = await findFiles(contentPath, contentPath, fileExtensions, exclude);
@@ -1015,11 +902,13 @@ async function buildDocument(file, embeddingOptions) {
     return { ok: false, stage: "parse", error: toError(error) };
   }
   let embedding;
+  let serializedEmbedding;
   try {
     embedding = await generateEmbedding(parsed.embeddingText, {
       ...embeddingOptions,
       intent: embeddingOptions.intent ?? "document"
     });
+    serializedEmbedding = JSON.stringify(embedding);
   } catch (error) {
     return { ok: false, stage: "embed", error: toError(error) };
   }
@@ -1033,6 +922,7 @@ async function buildDocument(file, embeddingOptions) {
       tags: parsed.tags,
       serializedTags: parsed.serializedTags,
       embedding,
+      serializedEmbedding,
       metadata: parsed.metadata
     }
   };
@@ -1117,7 +1007,7 @@ function createInsertStatement(document, quotedTableName) {
       document.content,
       document.folder,
       document.serializedTags,
-      JSON.stringify(document.embedding)
+      document.serializedEmbedding
     ]
   };
 }
@@ -1173,7 +1063,7 @@ async function search(options) {
     query,
     limit = 10,
     tableName = "articles",
-    embeddingOptions = {},
+    embeddingOptions,
     candidates,
     exact = false
   } = options;
@@ -1185,6 +1075,9 @@ async function search(options) {
     "embedding index name"
   );
   const candidateCount = normalizeSearchCandidates(candidates, resultLimit);
+  if (embeddingOptions === void 0) {
+    throw new TypeError("embeddingOptions is required");
+  }
   const queryEmbedding = await generateEmbedding(query, {
     ...embeddingOptions,
     intent: embeddingOptions.intent ?? "query"

package/docs/API.md

@@ -113,7 +113,7 @@ Indexes Markdown files from a directory on disk.
 interface IndexerOptions {
   client: Client | DatabaseAdapter;
   contentPath: string;
-  embeddingOptions?: EmbeddingOptions;
+  embeddingOptions: EmbeddingOptions;
   fileExtensions?: string[];
   exclude?: string[];
   tableName?: string;
@@ -187,7 +187,16 @@ class IndexingError extends Error {
 import { indexContent, IndexingError } from "libsql-search";
 
 try {
-  await indexContent({ client, contentPath: "./content" });
+  await indexContent({
+    client,
+    contentPath: "./content",
+    embeddingOptions: {
+      provider: "openai-compatible",
+      baseUrl: process.env.EMBEDDING_BASE_URL!,
+      model: "bge-large-en-v1.5",
+      dimensions: 1024,
+    },
+  });
 } catch (error) {
   if (error instanceof IndexingError) {
     console.error(error.phase, error.failures);
@@ -212,7 +221,7 @@ interface SearchOptions {
   query: string;
   limit?: number;
   tableName?: string;
-  embeddingOptions?: EmbeddingOptions;
+  embeddingOptions: EmbeddingOptions;
   candidates?: number;
   exact?: boolean;
 }
@@ -246,7 +255,7 @@ Controls how many rows the index returns for the exact re-rank. It must be an in
 
 ```ts
 // Trade query cost for recall on a large corpus
-const results = await search({ client, query, limit: 10, candidates: 200 });
+const results = await search({ client, query, embeddingOptions, limit: 10, candidates: 200 });
 ```
 
 `candidates` has no effect when `exact` is `true` — that path scans every row — but it is **still validated**. `search({ exact: true, limit: 10, candidates: 5 })` throws, exactly as it would on the index path. Validity does not depend on which path a call happens to take.
@@ -262,7 +271,7 @@ Related exported constants:
 Set `exact: true` to bypass the index and score every row in the table.
 
 ```ts
-const results = await search({ client, query, exact: true });
+const results = await search({ client, query, embeddingOptions, exact: true });
 ```
 
 This is the guaranteed-exact path: it computes `vector_distance_cos` for every row with a non-`NULL` embedding, sorts by `(distance, id)`, and trims to `limit`. Cost grows linearly with table size, so it is intended for small corpora, correctness checks against the index path, and tables that have no vector index.
@@ -330,8 +339,7 @@ All retrieval helpers validate `tableName` before executing SQL, and all of them
 
 ```ts
 interface EmbeddingOptions {
-  provider?:
-    | "local"
+  provider:
     | "cloudflare"
     | "mistral"
     | "gemini"
@@ -353,7 +361,7 @@ interface EmbeddingOptions {
 
 Important option rules:
 
-- `provider` defaults to `local`
+- `provider` is required; every provider is an external service
 - `maxLength` defaults to `8000`
 - `timeoutMs` defaults to `30000`
 - `model` is only used by `openai-compatible`
@@ -364,7 +372,6 @@ Important option rules:
 
 Dimension rules:
 
-- local: fixed `384`
 - Cloudflare: fixed `1024`
 - Mistral: fixed `1024`
 - Gemini: default `3072`, allowed integer range `128-3072`
@@ -373,7 +380,7 @@ Dimension rules:
 
 See [Provider matrix and credential rules](./PROVIDERS.md) for the canonical provider table.
 
-### `generateEmbedding(text, options?)`
+### `generateEmbedding(text, options)`
 
 Generates one embedding vector.
 
@@ -385,15 +392,15 @@ const embedding = await generateEmbedding("deploy docs", {
 });
 ```
 
-### `generateEmbeddings(texts, options?)`
+### `generateEmbeddings(texts, options)`
 
 Generates an ordered batch of embeddings.
 
-- empty batches return `[]` without loading the local model or making a hosted call
+- empty batches return `[]` without configuring credentials or making a provider call
 - OpenAI batches above `2048` inputs are rejected before network work
 - `openai-compatible` batches are chunked sequentially according to `batchSize`
 
-### `createEmbeddingProvider(options?)`
+### `createEmbeddingProvider(options)`
 
 Creates a provider client with immutable metadata and an `embed(texts, options?)` method.
 
@@ -413,7 +420,7 @@ Provider clients return a rich `EmbeddingBatchResult`; the compatibility helpers
 
 Hosted provider clients are scoped to their current options. The library does not reuse a Cloudflare, Mistral, Gemini, or OpenAI client across different credential sets or configurations.
 
-### `getEmbeddingProviderMetadata(options?)`
+### `getEmbeddingProviderMetadata(options)`
 
 Returns the same metadata exposed by `createEmbeddingProvider(options).metadata` without resolving hosted-provider credentials.
 
@@ -422,7 +429,6 @@ Metadata shape:
 ```ts
 interface EmbeddingProviderMetadata {
   name:
-    | "local"
     | "cloudflare"
     | "mistral"
     | "gemini"
@@ -451,7 +457,6 @@ Batch interpretation:
 interface EmbeddingBatchResult {
   embeddings: number[][];
   provider:
-    | "local"
     | "cloudflare"
     | "mistral"
     | "gemini"
@@ -474,7 +479,7 @@ Validates provider responses before they reach the database:
 
 ### `padEmbedding(embedding, targetDimensions)`
 
-Pads or truncates a vector to the target width. This is exported for compatibility and migration workflows, but the current local provider uses its native `384` dimensions rather than padding by default.
+Pads or truncates a vector to the target width. This is exported for compatibility and migration workflows; provider adapters otherwise validate and preserve the vectors returned by their external service.
 
 ### `prepareTextForEmbedding(fields)`
 

package/docs/INDEXING.md

@@ -18,13 +18,18 @@ The slug is derived from the file path relative to `contentPath`.
 `indexContent()` replaces the whole target table:
 
 ```ts
+const embeddingOptions = {
+  provider: "openai-compatible" as const,
+  baseUrl: process.env.EMBEDDING_BASE_URL!,
+  model: "bge-large-en-v1.5",
+  dimensions: 1024,
+};
+
 await indexContent({
   client,
   contentPath: "./content",
-  tableName: "articles_local_384",
-  embeddingOptions: {
-    provider: "local",
-  },
+  tableName: "articles_bge_1024",
+  embeddingOptions,
 });
 ```
 
@@ -69,7 +74,7 @@ Both are governed by `failurePolicy` like any other build failure, so they abort
 import { indexContent, IndexingError } from "libsql-search";
 
 try {
-  await indexContent({ client, contentPath: "./content" });
+  await indexContent({ client, contentPath: "./content", embeddingOptions });
 } catch (error) {
   if (error instanceof IndexingError) {
     for (const failure of error.failures) {
@@ -87,6 +92,7 @@ By default one bad file aborts the whole rebuild. To index everything that can b
 const result = await indexContent({
   client,
   contentPath: "./content",
+  embeddingOptions,
   failurePolicy: "skip",
 });
 
@@ -105,6 +111,7 @@ An empty source directory throws by default, because silently leaving stale rows
 await indexContent({
   client,
   contentPath: "./content",
+  embeddingOptions,
   allowEmptyIndex: true,
 });
 ```
@@ -173,7 +180,6 @@ Many projects wire indexing into a dedicated script and call it before their sit
 
 ## Runtime Notes
 
-- local embeddings may download and cache a model on the first run
 - Node users need `@libsql/client` installed alongside the package, at `^0.15.0 || ^0.17.0`; the packaged build is smoke-tested against both arms (`0.15.15` and `0.17.4`), which covers table and vector-index creation. `batch()` rollback behaves identically on both at the contract level, though its error text differs — see [Version differences](./TROUBLESHOOTING.md#libsqlclient-version-differences). Upgrading the client is not a prerequisite for upgrading this package. Deno/JSR users are not covered by that range and should pin the client themselves — see [Install](../README.md#install)
-- hosted providers send indexed or queried text to external services
+- all embedding providers send indexed or queried text to external services; this library never loads a model in-process
 - the repository validates package build and `deno check`, but indexing still depends on filesystem access

package/docs/INTEGRATIONS.md

@@ -55,13 +55,6 @@ These presets keep credentials out of the source file while making dimensions an
 
 ```ts
 const providerPresets = {
-  local: {
-    tableName: "articles_local_384",
-    dimensions: 384,
-    embeddingOptions: {
-      provider: "local" as const,
-    },
-  },
   cloudflare: {
     tableName: "articles_cf_bgem3_1024",
     dimensions: 1024,
@@ -137,9 +130,13 @@ export const POST: APIRoute = async ({ request }) => {
     client,
     query,
     limit,
-    tableName: "articles_local_384",
+    tableName: "articles_tei_1024",
     embeddingOptions: {
-      provider: "local",
+      provider: "openai-compatible",
+      baseUrl: process.env.EMBEDDING_BASE_URL!,
+      model: process.env.EMBEDDING_MODEL!,
+      dimensions: 1024,
+      apiKey: process.env.EMBEDDING_API_KEY,
       intent: "query",
     },
   });
@@ -162,14 +159,14 @@ const client = createClient({
 });
 
 export async function getStaticPaths() {
-  const articles = await getAllArticles(client, "articles_local_384");
+  const articles = await getAllArticles(client, "articles_tei_1024");
 
   return articles.map((article) => ({
     params: { slug: article.slug },
   }));
 }
 
-const article = await getArticleBySlug(client, "guides/getting-started", "articles_local_384");
+const article = await getArticleBySlug(client, "guides/getting-started", "articles_tei_1024");
 ```
 
 ## Next.js Route Handler
@@ -191,9 +188,13 @@ export async function POST(request: NextRequest) {
     client,
     query,
     limit,
-    tableName: "articles_local_384",
+    tableName: "articles_tei_1024",
     embeddingOptions: {
-      provider: "local",
+      provider: "openai-compatible",
+      baseUrl: process.env.EMBEDDING_BASE_URL!,
+      model: process.env.EMBEDDING_MODEL!,
+      dimensions: 1024,
+      apiKey: process.env.EMBEDDING_API_KEY,
       intent: "query",
     },
   });
@@ -214,7 +215,7 @@ const client = createClient({
 });
 
 export async function generateStaticParams() {
-  const articles = await getAllArticles(client, "articles_local_384");
+  const articles = await getAllArticles(client, "articles_tei_1024");
 
   return articles.map((article) => ({
     slug: article.slug,
@@ -223,7 +224,7 @@ export async function generateStaticParams() {
 
 export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
   const { slug } = await params;
-  const article = await getArticleBySlug(client, slug, "articles_local_384");
+  const article = await getArticleBySlug(client, slug, "articles_tei_1024");
 
   return <article>{article?.title}</article>;
 }
@@ -241,13 +242,6 @@ const client = createClient({
 });
 
 const providerPresets = {
-  local: {
-    tableName: "articles_local_384",
-    dimensions: 384,
-    embeddingOptions: {
-      provider: "local" as const,
-    },
-  },
   cloudflare: {
     tableName: "articles_cf_bgem3_1024",
     dimensions: 1024,
@@ -299,7 +293,7 @@ const providerPresets = {
   },
 } as const;
 
-const provider = process.env.EMBEDDING_PROVIDER ?? "local";
+const provider = process.env.EMBEDDING_PROVIDER ?? "openai-compatible";
 
 if (!(provider in providerPresets)) {
   throw new Error(
@@ -349,4 +343,4 @@ await generateEmbeddings(["doc one", "doc two"], {
 });
 ```
 
-The repository test suite should not require real provider credentials. See [Testing guidance](./TESTING.md) for local model mocks, Gemini SDK mocks, and validation-before-network assertions.
+The repository test suite should not require real provider credentials. See [Testing guidance](./TESTING.md) for embedding-service mocks, Gemini SDK mocks, and validation-before-network assertions.

package/docs/MIGRATIONS.md

@@ -27,7 +27,7 @@ References:
 
 In practice, this means:
 
-- `384 local` and `1024 Mistral` can never share a table
+- a legacy `384` embedding space and `1024 Mistral` can never share a table
 - `1024 Cloudflare` and `1024 Mistral` still need separate rebuilds because equal width does not make the vectors compatible
 - a custom endpoint change at the same width still needs a new table because the model or serving stack may have changed
 
@@ -84,14 +84,14 @@ Re-running `createTable()` with the table's existing width is the fix. It is ide
 
 ```ts
 // Same name and same width as the existing table
-await createTable(client, "articles_local_384", 384);
+await createTable(client, "articles_legacy_384", 384);
 ```
 
 Equivalently, in SQL:
 
 ```sql
-CREATE INDEX IF NOT EXISTS "articles_local_384_embedding_idx"
-ON "articles_local_384"(libsql_vector_idx(embedding));
+CREATE INDEX IF NOT EXISTS "articles_legacy_384_embedding_idx"
+ON "articles_legacy_384"(libsql_vector_idx(embedding));
 ```
 
 Reindexing does not create the index; `indexContent()` only replaces rows. Any new table created by `createTable()` as part of a migration already has it, so this applies only to pre-existing tables you are carrying forward. Until the index exists, `search({ ..., exact: true })` keeps queries working on the exact full-scan path.
@@ -100,7 +100,7 @@ Reindexing does not create the index; `indexContent()` only replaces rows. Any n
 
 | From | To | Why a rebuild is required | Recommended table move |
 | --- | --- | --- | --- |
-| Legacy padded local `768` | Native local `384` | Old tables stored `384` model values plus zero padding; current local provider is a native `384`-dimension space | Build into `articles_local_384`, validate, then retire the legacy table |
+| Legacy in-process Transformers.js index | Any external provider | The runtime and provider were removed; every replacement service has its own embedding space | Build a parallel table named for the external provider/model, validate, then retire the legacy table |
 | Any `768` space | Any `1024` space | Width changes from `F32_BLOB(768)` to `F32_BLOB(1024)` | Create a new `1024` table and reindex |
 | Cloudflare `1024` | Mistral `1024` | Width stays the same, but provider/model space changes | Use a parallel `1024` table such as `articles_mistral_1024` |
 | Mistral `1024` | Cloudflare `1024` | Same reason in reverse | Use a parallel `1024` table such as `articles_cf_bgem3_1024` |
@@ -111,21 +111,21 @@ Reindexing does not create the index; `indexContent()` only replaces rows. Any n
 
 ## Scenario Notes
 
-### Legacy Local `768` To Native Local `384`
+### Legacy In-Process Embeddings To An External Service
 
-Earlier local migrations sometimes relied on zero padding to fit a `768`-wide table. The current local adapter emits the model's native `384` dimensions and rejects any other local dimension count.
+Versions that exposed the in-process Transformers.js provider produced a separate embedding space that this release can no longer query. Choose an external provider or separately deployed OpenAI-compatible service and rebuild every vector into a new table.
 
 Safe path:
 
 ```ts
-await createTable(client, "articles_local_384", 384);
+await createTable(client, "articles_bge_1024", 1024);
 ```
 
-Reindex into `articles_local_384`; do not keep writing new local vectors into the legacy padded table.
+Reindex into `articles_bge_1024` with the external service configuration; do not mix its vectors with the legacy table.
 
 ### `768` To `1024`
 
-Any move from `768` dimensions to `1024` dimensions changes the schema width. Examples include a legacy local table moving to Cloudflare or Mistral.
+Any move from `768` dimensions to `1024` dimensions changes the schema width. Examples include a legacy table moving to Cloudflare, Mistral, or a 1024-dimensional OpenAI-compatible service.
 
 ```ts
 await createTable(client, "articles_mistral_1024", 1024);

package/docs/PROVIDERS.md

@@ -2,9 +2,8 @@
 
 Use this page to choose an embedding provider, confirm the table width it needs, and understand what crosses a network boundary.
 
-`libsql-search` supports these provider values:
+`libsql-search` only talks to external embedding services; it never loads or hosts an embedding model in-process. It supports these provider values:
 
-- `local`
 - `cloudflare`
 - `mistral`
 - `gemini`
@@ -17,8 +16,7 @@ All providers share the same `EmbeddingOptions` surface:
 
 ```ts
 interface EmbeddingOptions {
-  provider?:
-    | "local"
+  provider:
     | "cloudflare"
     | "mistral"
     | "gemini"
@@ -40,7 +38,7 @@ interface EmbeddingOptions {
 
 Shared defaults and rules:
 
-- `provider` defaults to `local`
+- `provider` is required; there is no implicit embedding runtime or service
 - `maxLength` defaults to `8000` code units
 - `timeoutMs` defaults to `30000`
 - `indexContent()` defaults to `intent: "document"`
@@ -59,7 +57,6 @@ The `model` option is only used by `openai-compatible`.
 
 | Provider | Literal | Upstream model used by this adapter | Dimensions | Credentials | Batching | Network and privacy boundary | Cost and table planning |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| Local | `local` | `Xenova/all-MiniLM-L6-v2` | Fixed `384` | None | Sequential in-process | No hosted API call. First use may download model artifacts and cache them locally. | No hosted API bill. Table must be `F32_BLOB(384)`. |
 | Cloudflare Workers AI | `cloudflare` | `@cf/baai/bge-m3` | Fixed `1024` | `accountId` and `apiToken`, or `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` | Native batch in one request | Indexed and queried text is sent to Cloudflare. | Check Cloudflare pricing before large rebuilds. Table must be `F32_BLOB(1024)`. |
 | Mistral | `mistral` | `mistral-embed` | Fixed `1024` | `apiKey`, or `MISTRAL_API_KEY` | Native batch in one request | Indexed and queried text is sent to Mistral. | Check Mistral pricing before rebuilds. Table must be `F32_BLOB(1024)`. |
 | Gemini | `gemini` | `gemini-embedding-2` | Default `3072`; allowed integers `128-3072` | `apiKey`, or `GEMINI_API_KEY` | Sequential SDK request per input | Indexed and queried text is sent to Google. The adapter currently rewrites payload text by intent. | Check Gemini pricing before rebuilds. Table width must match the chosen dimension count exactly. |
@@ -68,23 +65,6 @@ The `model` option is only used by `openai-compatible`.
 
 ## Provider Notes
 
-### Local
-
-```ts
-embeddingOptions: {
-  provider: "local",
-}
-```
-
-- fixed at `384` dimensions
-- rejects any other `dimensions` value before loading the runtime
-- uses `@huggingface/transformers` lazily and caches the local pipeline by model name
-
-References:
-
-- [Transformers.js in Node.js](https://huggingface.co/docs/transformers.js/en/tutorials/node)
-- [Transformers.js environment and cache controls](https://huggingface.co/docs/transformers.js/en/api/env)
-
 ### Cloudflare Workers AI
 
 ```ts

package/docs/README.md

@@ -2,7 +2,7 @@
 
 This directory holds the longer-form reference material for `libsql-search`.
 
-- [Provider selection and configuration](./PROVIDERS.md): compare local, hosted, and custom embedding providers before you build an index
+- [Provider selection and configuration](./PROVIDERS.md): compare external and custom embedding providers before you build an index
 - [Integration examples](./INTEGRATIONS.md): reusable provider flow plus Astro and Next.js examples
 - [Migration and reindexing guide](./MIGRATIONS.md): table-width changes, provider/model swaps, and safe cutovers
 - [API reference](./API.md): exported functions, option shapes, and result data

package/docs/TESTING.md

@@ -9,30 +9,31 @@ Routine unit tests and CI should not make live embedding-provider calls and shou
 - validate option handling and response parsing with mocks first
 - assert failures happen before network calls when configuration is invalid
 
-The current test suite follows that pattern in `tests/embeddings.test.ts` and [`tests/huggingface-transformers.mock.ts`](../tests/huggingface-transformers.mock.ts).
+The current test suite follows that pattern in `tests/embeddings.test.ts` and [`tests/embedding-service.mock.ts`](../tests/embedding-service.mock.ts).
 
-## Local Provider Mocks
+## Shared Embedding Service Mock
 
-The local provider should use a lightweight Transformers.js mock instead of downloading the real model during routine tests.
+Indexer, search, and database tests use a deterministic OpenAI-compatible service mock. This keeps the tests on the same external-service boundary as production without making network calls.
 
 ```ts
 import {
-  huggingFaceTransformersMock,
-  resetHuggingFaceTransformersMock,
-} from "./huggingface-transformers.mock.js";
+  embeddingServiceMock,
+  resetEmbeddingServiceMock,
+  TEST_EMBEDDING_OPTIONS,
+} from "./embedding-service.mock.js";
 
 beforeEach(() => {
-  resetHuggingFaceTransformersMock();
+  resetEmbeddingServiceMock();
 });
 ```
 
-The repository source file is `huggingface-transformers.mock.ts`. The example keeps the `.js` import suffix because this repo's ESM TypeScript source uses explicit `.js` relative imports that resolve after compilation.
+The example keeps the `.js` import suffix because this repo's ESM TypeScript source uses explicit `.js` relative imports that resolve after compilation.
 
 Test the contract you care about:
 
-- the library requests `Xenova/all-MiniLM-L6-v2`
-- the call uses `pooling: "mean"` and `normalize: true`
-- non-`384` local dimensions fail before runtime loading
+- indexing and querying use the same endpoint, model, and dimensions
+- provider failures remain classified as build-stage failures
+- queued deterministic vectors exercise exact ranking and tie behavior
 
 ## HTTP Provider Mocks
 
@@ -116,9 +117,9 @@ Apply the same pattern to `GEMINI_API_KEY`, `MISTRAL_API_KEY`, `CLOUDFLARE_ACCOU
 Prefer tests that prove bad inputs fail locally:
 
 - unknown provider
+- missing provider
 - missing provider credentials
 - blank credentials where trimming is expected
-- invalid local dimensions
 - invalid Gemini dimensions
 - invalid `openai-compatible` `baseUrl`
 - invalid `openai-compatible` `batchSize`

package/docs/TROUBLESHOOTING.md

@@ -1,9 +1,5 @@
 # Troubleshooting
 
-Use the page that matches the failure mode:
-
-- [Sharp native module issues](./TROUBLESHOOTING-SHARP.md)
-
 Common operational checks:
 
 - verify you called `createTable()` before indexing or searching
@@ -15,8 +11,6 @@ Common operational checks:
 - after upgrading an existing Gemini index, fully re-embed with
   `gemini-embedding-2`; for 3072-dimensional Gemini indexes, recreate the table
   or use a new table name before rebuilding
-- after upgrading an existing local 768-dimensional padded index, create or
-  recreate a 384-dimensional table and fully re-index before querying it
 - if `search()` reports that the `<tableName>_embedding_idx` vector index could
   not be used, the table has no embedding vector index: re-run `createTable()`
   with the table's existing name and width to add it without touching rows, or

package/docs/TURSO.md

@@ -44,19 +44,26 @@ import { createTable, indexContent, search } from "libsql-search";
 const database = await connect("./local.db");
 const client = tursoAdapter(database);
 
-await createTable(client, "articles", 384);
+const embeddingOptions = {
+  provider: "openai-compatible" as const,
+  baseUrl: process.env.EMBEDDING_BASE_URL!,
+  model: "bge-large-en-v1.5",
+  dimensions: 1024,
+};
+
+await createTable(client, "articles", 1024);
 
 await indexContent({
   client,
   contentPath: "./content",
-  embeddingOptions: { provider: "local" },
+  embeddingOptions,
 });
 
 const results = await search({
   client,
   query: "how do I deploy my docs site",
   limit: 5,
-  embeddingOptions: { provider: "local" },
+  embeddingOptions,
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libsql-search",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Semantic search for static sites using libSQL/Turso with multi-provider embeddings",
   "type": "module",
   "packageManager": "pnpm@10.34.5",
@@ -75,7 +75,6 @@
     }
   },
   "dependencies": {
-    "@huggingface/transformers": "4.2.0",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {

package/docs/TROUBLESHOOTING-SHARP.md

@@ -1,65 +0,0 @@
-# Troubleshooting: Transitive `sharp` Install Errors
-
-`libsql-search` does not directly import `sharp`, but local embeddings use
-`@huggingface/transformers`, which currently brings in `sharp` as a transitive
-runtime dependency. If you see an install error mentioning `sharp`, it is
-usually a native-package install or approval issue.
-
-This page exists because the error can show up before your application reaches
-any `libsql-search` code.
-
-## Typical Error
-
-```text
-Cannot find module '../build/Release/sharp-*.node'
-```
-
-Or:
-
-```text
-Error: Something went wrong installing the "sharp" module
-```
-
-## Why It Happens
-
-With pnpm, native packages may need explicit build-script approval. If the
-relevant install script is blocked, the native binary is never downloaded or
-built.
-
-## What To Do
-
-First inspect which build scripts pnpm blocked:
-
-```bash
-pnpm ignored-builds
-```
-
-Then approve the package that is actually failing and reinstall:
-
-```bash
-pnpm approve-builds
-pnpm install
-```
-
-In the interactive `pnpm approve-builds` prompt, select `sharp` if that is the
-package reporting the native-module failure.
-
-For a committed repository-level fix, you can also allow the package explicitly
-in `pnpm-workspace.yaml` with `onlyBuiltDependencies`.
-
-## Relation To `libsql-search`
-
-- local embeddings use `@huggingface/transformers`
-- the first local embedding run may download a model at runtime
-- that runtime model download is separate from a pnpm native-module install
-  failure
-
-## Verification
-
-After reinstalling, rerun the command that originally failed. If your app uses
-`sharp` directly, verify that import in your own project context.
-
-## Additional Resources
-
-- [pnpm approve-builds](https://pnpm.io/10.x/cli/approve-builds)
-- [Sharp installation docs](https://sharp.pixelplumbing.com/install)