@browser-ai/web-llm 2.1.0 → 2.1.2

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult } from '@ai-sdk/provider';
-import { AppConfig, InitProgressReport, MLCEngineConfig } from '@mlc-ai/web-llm';
+import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult, EmbeddingModelV3, EmbeddingModelV3CallOptions, EmbeddingModelV3Result, ProviderV3 } from '@ai-sdk/provider';
+import { AppConfig, InitProgressReport, MLCEngineConfig, MLCEngineInterface } from '@mlc-ai/web-llm';
 export { InitProgressReport as WebLLMProgress, WebWorkerMLCEngineHandler } from '@mlc-ai/web-llm';
 import { UIMessage } from 'ai';
 
@@ -75,6 +75,11 @@ declare global {
         gpu?: GPU;
     }
 }
+/**
+ * Check if the browser supports WebLLM (WebGPU)
+ */
+declare function doesBrowserSupportWebLLM(): boolean;
+
 type WebLLMModelId = string;
 interface WebLLMSettings {
     /**
@@ -97,11 +102,6 @@ interface WebLLMSettings {
      */
     worker?: Worker;
 }
-/**
- * Check if the browser supports WebGPU (required for WebLLM).
- * @returns boolean - true if WebGPU API is available
- */
-declare function doesBrowserSupportWebLLM(): boolean;
 declare class WebLLMLanguageModel implements LanguageModelV3 {
     readonly specificationVersion = "v3";
     readonly modelId: WebLLMModelId;
@@ -162,11 +162,115 @@ declare class WebLLMLanguageModel implements LanguageModelV3 {
     doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
 }
 
+type WebLLMEmbeddingModelId = string;
+interface WebLLMEmbeddingSettings {
+    /**
+     * Custom app configuration for WebLLM
+     */
+    appConfig?: AppConfig;
+    /**
+     * Progress callback for model initialization
+     */
+    initProgressCallback?: (progress: InitProgressReport) => void;
+    /**
+     * Engine configuration options
+     */
+    engineConfig?: MLCEngineConfig;
+    /**
+     * A web worker instance to run the model in.
+     * When provided, the model will run in a separate thread.
+     *
+     * @default undefined
+     */
+    worker?: Worker;
+    /**
+     * Maximum number of texts to embed in a single call.
+     * @default 100
+     */
+    maxEmbeddingsPerCall?: number;
+}
+declare class WebLLMEmbeddingModel implements EmbeddingModelV3 {
+    readonly specificationVersion = "v3";
+    readonly provider = "web-llm";
+    readonly modelId: WebLLMEmbeddingModelId;
+    readonly maxEmbeddingsPerCall: number;
+    readonly supportsParallelCalls = false;
+    private readonly config;
+    private engine?;
+    private isInitialized;
+    private initializationPromise?;
+    constructor(modelId: WebLLMEmbeddingModelId, options?: WebLLMEmbeddingSettings);
+    /**
+     * Check if the model is initialized and ready to use
+     */
+    get isModelInitialized(): boolean;
+    private getEngine;
+    private _initializeEngine;
+    /**
+     * Check the availability of the WebLLM embedding model
+     * @returns Promise resolving to "unavailable", "available", or "downloadable"
+     */
+    availability(): Promise<Availability>;
+    /**
+     * Creates an engine session with download progress monitoring.
+     *
+     * @example
+     * ```typescript
+     * const engine = await model.createSessionWithProgress(
+     *   (progress) => {
+     *     console.log(`Download progress: ${Math.round(progress.progress * 100)}%`);
+     *   }
+     * );
+     * ```
+     *
+     * @param onInitProgress Optional callback receiving progress reports during model download
+     * @returns Promise resolving to a configured WebLLM engine
+     * @throws {LoadSettingError} When WebLLM isn't available or model is unavailable
+     */
+    createSessionWithProgress(onInitProgress?: (progress: InitProgressReport) => void): Promise<MLCEngineInterface>;
+    /**
+     * Embed texts using the WebLLM embedding model
+     */
+    doEmbed(options: EmbeddingModelV3CallOptions): Promise<EmbeddingModelV3Result>;
+}
+
+interface WebLLMProvider extends ProviderV3 {
+    (modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+    /**
+     * Creates a model for text generation.
+     */
+    languageModel(modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+    /**
+     * Creates a model for text generation.
+     */
+    chat(modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+    /**
+     * Creates a model for text embeddings.
+     */
+    embedding(modelId: WebLLMEmbeddingModelId, settings?: WebLLMEmbeddingSettings): EmbeddingModelV3;
+    /**
+     * Creates a model for text embeddings.
+     */
+    embeddingModel: (modelId: WebLLMEmbeddingModelId, settings?: WebLLMEmbeddingSettings) => EmbeddingModelV3;
+}
+/**
+ * Create a WebLLM provider instance.
+ */
+declare function createWebLLM(): WebLLMProvider;
 /**
- * Create a new WebLLMLanguageModel.
- * @param modelId The model ID to use (e.g., 'Llama-3.1-8B-Instruct-q4f32_1-MLC')
- * @param settings Options for the model
+ * Default WebLLM provider instance
+ *
+ * @example
+ * ```typescript
+ * import { webLLM } from "@browser-ai/web-llm";
+ *
+ * // Language model
+ * const chat = webLLM("Llama-3.2-3B-Instruct-q4f16_1-MLC");
+ *
+ * // Embedding model
+ * const embed = webLLM.embeddingModel("snowflake-arctic-embed-m-q0f32-MLC-b32");
+ * ```
  */
-declare function webLLM(modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+declare const webLLM: WebLLMProvider;
 
-export { WebLLMLanguageModel, type WebLLMModelId, type WebLLMSettings, type WebLLMUIMessage, doesBrowserSupportWebLLM, webLLM };
+export { WebLLMEmbeddingModel, type WebLLMEmbeddingModelId, type WebLLMEmbeddingSettings, WebLLMLanguageModel, type WebLLMModelId, type WebLLMProvider, type WebLLMSettings, type WebLLMUIMessage, createWebLLM, doesBrowserSupportWebLLM, webLLM };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult } from '@ai-sdk/provider';
-import { AppConfig, InitProgressReport, MLCEngineConfig } from '@mlc-ai/web-llm';
+import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult, EmbeddingModelV3, EmbeddingModelV3CallOptions, EmbeddingModelV3Result, ProviderV3 } from '@ai-sdk/provider';
+import { AppConfig, InitProgressReport, MLCEngineConfig, MLCEngineInterface } from '@mlc-ai/web-llm';
 export { InitProgressReport as WebLLMProgress, WebWorkerMLCEngineHandler } from '@mlc-ai/web-llm';
 import { UIMessage } from 'ai';
 
@@ -75,6 +75,11 @@ declare global {
         gpu?: GPU;
     }
 }
+/**
+ * Check if the browser supports WebLLM (WebGPU)
+ */
+declare function doesBrowserSupportWebLLM(): boolean;
+
 type WebLLMModelId = string;
 interface WebLLMSettings {
     /**
@@ -97,11 +102,6 @@ interface WebLLMSettings {
      */
     worker?: Worker;
 }
-/**
- * Check if the browser supports WebGPU (required for WebLLM).
- * @returns boolean - true if WebGPU API is available
- */
-declare function doesBrowserSupportWebLLM(): boolean;
 declare class WebLLMLanguageModel implements LanguageModelV3 {
     readonly specificationVersion = "v3";
     readonly modelId: WebLLMModelId;
@@ -162,11 +162,115 @@ declare class WebLLMLanguageModel implements LanguageModelV3 {
     doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
 }
 
+type WebLLMEmbeddingModelId = string;
+interface WebLLMEmbeddingSettings {
+    /**
+     * Custom app configuration for WebLLM
+     */
+    appConfig?: AppConfig;
+    /**
+     * Progress callback for model initialization
+     */
+    initProgressCallback?: (progress: InitProgressReport) => void;
+    /**
+     * Engine configuration options
+     */
+    engineConfig?: MLCEngineConfig;
+    /**
+     * A web worker instance to run the model in.
+     * When provided, the model will run in a separate thread.
+     *
+     * @default undefined
+     */
+    worker?: Worker;
+    /**
+     * Maximum number of texts to embed in a single call.
+     * @default 100
+     */
+    maxEmbeddingsPerCall?: number;
+}
+declare class WebLLMEmbeddingModel implements EmbeddingModelV3 {
+    readonly specificationVersion = "v3";
+    readonly provider = "web-llm";
+    readonly modelId: WebLLMEmbeddingModelId;
+    readonly maxEmbeddingsPerCall: number;
+    readonly supportsParallelCalls = false;
+    private readonly config;
+    private engine?;
+    private isInitialized;
+    private initializationPromise?;
+    constructor(modelId: WebLLMEmbeddingModelId, options?: WebLLMEmbeddingSettings);
+    /**
+     * Check if the model is initialized and ready to use
+     */
+    get isModelInitialized(): boolean;
+    private getEngine;
+    private _initializeEngine;
+    /**
+     * Check the availability of the WebLLM embedding model
+     * @returns Promise resolving to "unavailable", "available", or "downloadable"
+     */
+    availability(): Promise<Availability>;
+    /**
+     * Creates an engine session with download progress monitoring.
+     *
+     * @example
+     * ```typescript
+     * const engine = await model.createSessionWithProgress(
+     *   (progress) => {
+     *     console.log(`Download progress: ${Math.round(progress.progress * 100)}%`);
+     *   }
+     * );
+     * ```
+     *
+     * @param onInitProgress Optional callback receiving progress reports during model download
+     * @returns Promise resolving to a configured WebLLM engine
+     * @throws {LoadSettingError} When WebLLM isn't available or model is unavailable
+     */
+    createSessionWithProgress(onInitProgress?: (progress: InitProgressReport) => void): Promise<MLCEngineInterface>;
+    /**
+     * Embed texts using the WebLLM embedding model
+     */
+    doEmbed(options: EmbeddingModelV3CallOptions): Promise<EmbeddingModelV3Result>;
+}
+
+interface WebLLMProvider extends ProviderV3 {
+    (modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+    /**
+     * Creates a model for text generation.
+     */
+    languageModel(modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+    /**
+     * Creates a model for text generation.
+     */
+    chat(modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+    /**
+     * Creates a model for text embeddings.
+     */
+    embedding(modelId: WebLLMEmbeddingModelId, settings?: WebLLMEmbeddingSettings): EmbeddingModelV3;
+    /**
+     * Creates a model for text embeddings.
+     */
+    embeddingModel: (modelId: WebLLMEmbeddingModelId, settings?: WebLLMEmbeddingSettings) => EmbeddingModelV3;
+}
+/**
+ * Create a WebLLM provider instance.
+ */
+declare function createWebLLM(): WebLLMProvider;
 /**
- * Create a new WebLLMLanguageModel.
- * @param modelId The model ID to use (e.g., 'Llama-3.1-8B-Instruct-q4f32_1-MLC')
- * @param settings Options for the model
+ * Default WebLLM provider instance
+ *
+ * @example
+ * ```typescript
+ * import { webLLM } from "@browser-ai/web-llm";
+ *
+ * // Language model
+ * const chat = webLLM("Llama-3.2-3B-Instruct-q4f16_1-MLC");
+ *
+ * // Embedding model
+ * const embed = webLLM.embeddingModel("snowflake-arctic-embed-m-q0f32-MLC-b32");
+ * ```
  */
-declare function webLLM(modelId: WebLLMModelId, settings?: WebLLMSettings): WebLLMLanguageModel;
+declare const webLLM: WebLLMProvider;
 
-export { WebLLMLanguageModel, type WebLLMModelId, type WebLLMSettings, type WebLLMUIMessage, doesBrowserSupportWebLLM, webLLM };
+export { WebLLMEmbeddingModel, type WebLLMEmbeddingModelId, type WebLLMEmbeddingSettings, WebLLMLanguageModel, type WebLLMModelId, type WebLLMProvider, type WebLLMSettings, type WebLLMUIMessage, createWebLLM, doesBrowserSupportWebLLM, webLLM };

package/dist/index.js

@@ -20,8 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  WebLLMEmbeddingModel: () => WebLLMEmbeddingModel,
   WebLLMLanguageModel: () => WebLLMLanguageModel,
-  WebWorkerMLCEngineHandler: () => import_web_llm2.WebWorkerMLCEngineHandler,
+  WebWorkerMLCEngineHandler: () => import_web_llm3.WebWorkerMLCEngineHandler,
+  createWebLLM: () => createWebLLM,
   doesBrowserSupportWebLLM: () => doesBrowserSupportWebLLM,
   webLLM: () => webLLM
 });
@@ -983,7 +985,7 @@ ${existingContent}` : "")
   ];
 }
 
-// src/web-llm-language-model.ts
+// src/utils/browser.ts
 function isMobile() {
   if (typeof navigator === "undefined") return false;
   return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
@@ -1000,6 +1002,8 @@ function checkWebGPU() {
 function doesBrowserSupportWebLLM() {
   return checkWebGPU();
 }
+
+// src/web-llm-language-model.ts
 function extractToolName(content) {
   const jsonMatch = content.match(/\{\s*"name"\s*:\s*"([^"]+)"/);
   if (jsonMatch) {
@@ -1142,7 +1146,8 @@ var WebLLMLanguageModel = class {
     responseFormat,
     seed,
     tools,
-    toolChoice
+    toolChoice,
+    providerOptions
   }) {
     const warnings = [];
     const functionTools = (tools ?? []).filter(isFunctionTool).map((tool) => ({
@@ -1209,6 +1214,12 @@ var WebLLMLanguageModel = class {
       top_p: topP,
       seed
     };
+    if (providerOptions?.extra_body) {
+      requestOptions.extra_body = {
+        enable_thinking: providerOptions.extra_body.enable_thinking,
+        enable_latency_breakdown: providerOptions.extra_body.enable_latency_breakdown
+      };
+    }
     if (responseFormat?.type === "json") {
       requestOptions.response_format = {
         type: "json_object",
@@ -1714,17 +1725,211 @@ var WebLLMLanguageModel = class {
   }
 };
 
-// src/index.ts
+// src/web-llm-embedding-model.ts
 var import_web_llm2 = require("@mlc-ai/web-llm");
+var WebLLMEmbeddingModel = class {
+  constructor(modelId, options = {}) {
+    this.specificationVersion = "v3";
+    this.provider = "web-llm";
+    this.supportsParallelCalls = false;
+    this.isInitialized = false;
+    this.modelId = modelId;
+    this.maxEmbeddingsPerCall = options.maxEmbeddingsPerCall ?? 100;
+    this.config = {
+      provider: this.provider,
+      modelId,
+      options
+    };
+  }
+  /**
+   * Check if the model is initialized and ready to use
+   */
+  get isModelInitialized() {
+    return this.isInitialized;
+  }
+  async getEngine(options, onInitProgress) {
+    const availability = await this.availability();
+    if (availability === "unavailable") {
+      throw new LoadSettingError({
+        message: "WebLLM is not available. This library requires a browser with WebGPU support."
+      });
+    }
+    if (this.engine && this.isInitialized) return this.engine;
+    if (this.initializationPromise) {
+      await this.initializationPromise;
+      if (this.engine) return this.engine;
+    }
+    this.initializationPromise = this._initializeEngine(
+      options,
+      onInitProgress
+    );
+    await this.initializationPromise;
+    if (!this.engine) {
+      throw new LoadSettingError({
+        message: "Engine initialization failed"
+      });
+    }
+    return this.engine;
+  }
+  async _initializeEngine(options, onInitProgress) {
+    try {
+      const engineConfig = {
+        ...this.config.options.engineConfig,
+        ...options,
+        initProgressCallback: onInitProgress || this.config.options.initProgressCallback
+      };
+      if (this.config.options.worker) {
+        this.engine = await (0, import_web_llm2.CreateWebWorkerMLCEngine)(
+          this.config.options.worker,
+          this.modelId,
+          engineConfig
+        );
+      } else {
+        this.engine = new import_web_llm2.MLCEngine(engineConfig);
+        await this.engine.reload(this.modelId);
+      }
+      this.isInitialized = true;
+    } catch (error) {
+      this.engine = void 0;
+      this.isInitialized = false;
+      this.initializationPromise = void 0;
+      throw new LoadSettingError({
+        message: `Failed to initialize WebLLM embedding engine: ${error instanceof Error ? error.message : "Unknown error"}`
+      });
+    }
+  }
+  /**
+   * Check the availability of the WebLLM embedding model
+   * @returns Promise resolving to "unavailable", "available", or "downloadable"
+   */
+  async availability() {
+    if (this.isInitialized) {
+      return "available";
+    }
+    if (this.config.options.worker && isMobile()) {
+      return "downloadable";
+    }
+    const supported = checkWebGPU();
+    return supported ? "downloadable" : "unavailable";
+  }
+  /**
+   * Creates an engine session with download progress monitoring.
+   *
+   * @example
+   * ```typescript
+   * const engine = await model.createSessionWithProgress(
+   *   (progress) => {
+   *     console.log(`Download progress: ${Math.round(progress.progress * 100)}%`);
+   *   }
+   * );
+   * ```
+   *
+   * @param onInitProgress Optional callback receiving progress reports during model download
+   * @returns Promise resolving to a configured WebLLM engine
+   * @throws {LoadSettingError} When WebLLM isn't available or model is unavailable
+   */
+  async createSessionWithProgress(onInitProgress) {
+    return this.getEngine(void 0, onInitProgress);
+  }
+  /**
+   * Embed texts using the WebLLM embedding model
+   */
+  async doEmbed(options) {
+    const { values, abortSignal } = options;
+    if (values.length > this.maxEmbeddingsPerCall) {
+      throw new TooManyEmbeddingValuesForCallError({
+        provider: this.provider,
+        modelId: this.modelId,
+        maxEmbeddingsPerCall: this.maxEmbeddingsPerCall,
+        values
+      });
+    }
+    if (abortSignal?.aborted) {
+      throw new Error("Operation was aborted");
+    }
+    const engine = await this.getEngine();
+    const abortHandler = () => {
+      engine.interruptGenerate();
+    };
+    if (abortSignal) {
+      abortSignal.addEventListener("abort", abortHandler);
+    }
+    try {
+      const response = await engine.embeddings.create({
+        input: values,
+        model: this.modelId,
+        ...abortSignal && !this.config.options.worker && { signal: abortSignal }
+      });
+      const sortedEmbeddings = response.data.sort((a, b) => a.index - b.index).map((e) => e.embedding);
+      return {
+        embeddings: sortedEmbeddings,
+        usage: {
+          tokens: response.usage.total_tokens
+        },
+        providerMetadata: {
+          webllm: {
+            model: response.model,
+            promptTokens: response.usage.prompt_tokens,
+            totalTokens: response.usage.total_tokens,
+            prefillTokensPerSecond: response.usage.extra?.prefill_tokens_per_s
+          }
+        },
+        warnings: []
+      };
+    } catch (error) {
+      throw new Error(
+        `WebLLM embedding failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    } finally {
+      if (abortSignal) {
+        abortSignal.removeEventListener("abort", abortHandler);
+      }
+    }
+  }
+};
+
+// src/index.ts
+var import_web_llm3 = require("@mlc-ai/web-llm");
 
 // src/web-llm-provider.ts
-function webLLM(modelId, settings) {
-  return new WebLLMLanguageModel(modelId, settings);
+function createWebLLM() {
+  const createLanguageModel = (modelId, settings) => {
+    return new WebLLMLanguageModel(modelId, settings);
+  };
+  const createEmbeddingModel = (modelId, settings) => {
+    return new WebLLMEmbeddingModel(modelId, settings);
+  };
+  const provider = function(modelId, settings) {
+    if (new.target) {
+      throw new Error(
+        "The WebLLM model function cannot be called with the new keyword."
+      );
+    }
+    return createLanguageModel(modelId, settings);
+  };
+  provider.specificationVersion = "v3";
+  provider.languageModel = createLanguageModel;
+  provider.chat = createLanguageModel;
+  provider.embedding = createEmbeddingModel;
+  provider.embeddingModel = createEmbeddingModel;
+  provider.imageModel = (modelId) => {
+    throw new NoSuchModelError({ modelId, modelType: "imageModel" });
+  };
+  provider.speechModel = (modelId) => {
+    throw new NoSuchModelError({ modelId, modelType: "speechModel" });
+  };
+  provider.transcriptionModel = (modelId) => {
+    throw new NoSuchModelError({ modelId, modelType: "transcriptionModel" });
+  };
+  return provider;
 }
+var webLLM = createWebLLM();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  WebLLMEmbeddingModel,
   WebLLMLanguageModel,
   WebWorkerMLCEngineHandler,
+  createWebLLM,
   doesBrowserSupportWebLLM,
   webLLM
 });