@firebase/ai 2.12.0 → 2.13.0-20260526192810

package/dist/esm/src/methods/chrome-adapter.d.ts

@@ -16,7 +16,9 @@
  */
 import { CountTokensRequest, GenerateContentRequest, InferenceMode, OnDeviceParams } from '../types';
 import { ChromeAdapter } from '../types/chrome-adapter';
-import { LanguageModel } from '../types/language-model';
+import { Availability, LanguageModel, LanguageModelExpected } from '../types/language-model';
+export declare const defaultExpectedInputs: LanguageModelExpected[];
+export declare const defaultExpectedOutputs: LanguageModelExpected[];
 /**
  * Defines an inference "backend" that uses Chrome's on-device model,
  * and encapsulates logic for detecting when on-device inference is
@@ -26,8 +28,7 @@ export declare class ChromeAdapterImpl implements ChromeAdapter {
     languageModelProvider: LanguageModel;
     mode: InferenceMode;
     static SUPPORTED_MIME_TYPES: string[];
-    private isDownloading;
-    private downloadPromise;
+    downloadPromise: Promise<LanguageModel | void> | null;
     private oldSession;
     onDeviceParams: OnDeviceParams;
     constructor(languageModelProvider: LanguageModel, mode: InferenceMode, onDeviceParams?: OnDeviceParams);
@@ -38,7 +39,7 @@ export declare class ChromeAdapterImpl implements ChromeAdapter {
      *   the mode
      *   API existence
      *   prompt formatting
-     *   model availability, including triggering download if necessary
+     *   model availability
      *
      *
      * Pros: callers needn't be concerned with details of on-device availability.</p>
@@ -75,12 +76,12 @@ export declare class ChromeAdapterImpl implements ChromeAdapter {
     /**
      * Encapsulates logic to get availability and download a model if one is downloadable.
      */
-    private downloadIfAvailable;
+    downloadIfAvailable(onDownloadProgress?: (progressValue: number) => void): Promise<Availability | undefined>;
     /**
      * Triggers out-of-band download of an on-device model.
      *
-     * Chrome only downloads models as needed. Chrome knows a model is needed when code calls
-     * LanguageModel.create.
+     * Chrome may automatically begin a download on startup or
+     * it may trigger a download when code calls LanguageModel.create.
      *
      * Since Chrome manages the download, the SDK can only avoid redundant download requests by
      * tracking if a download has previously been requested.

package/dist/esm/src/models/generative-model.d.ts

@@ -32,6 +32,35 @@ export declare class GenerativeModel extends AIModel {
     toolConfig?: ToolConfig;
     systemInstruction?: Content;
     constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions, chromeAdapter?: ChromeAdapter | undefined);
+    /**
+     * Initializes on-device models.
+     *
+     * @remarks
+     * This may trigger a download on first
+     * use. Wait for this promise to complete before calling inference
+     * methods if you want to ensure the device models are ready before
+     * any calls. Calling inference methods before the device is ready
+     * will result in a cloud fallback if `inferenceMode` is set to
+     * `PREFER_ON_DEVICE`, and an error if set to `ONLY_ON_DEVICE`.
+     *
+     * IMPORTANT: This call must be made on or after a user has interacted
+     * with the page (for example, through a button click or key press).
+     * If it is called without a user interaction, and it requires a download,
+     * this will cause an error.
+     *
+     * See the
+     * {@link https://developer.chrome.com/docs/ai/prompt-api#use_the_prompt_api | Prompt API docs }
+     * for more details on this requirement.
+     *
+     * @param onDownloadProgress A callback called repeatedly as the
+     * download progresses that provides a `progressValue` between 0
+     * and 1 representing how much of the download is complete. This
+     * will be ignored if `monitor` was populated in
+     * {@link LanguageModelCreateOptions}.
+     *
+     * @public
+     */
+    initializeDeviceModel(onDownloadProgress?: (progressValue: number) => void): Promise<void>;
     /**
      * Makes a single non-streaming call to the model
      * and returns an object containing a single {@link GenerateContentResponse}.

package/dist/esm/src/types/chrome-adapter.d.ts

@@ -23,7 +23,7 @@ import { CountTokensRequest, GenerateContentRequest } from './requests';
  *
  * These methods should not be called directly by the user.
  *
- * @beta
+ * @public
  */
 export interface ChromeAdapter {
     /**

package/dist/esm/src/types/enums.d.ts

@@ -415,7 +415,7 @@ export type ResponseModality = (typeof ResponseModality)[keyof typeof ResponseMo
  * cloud-hosted model. If not available, the SDK will fall back to an
  * on-device model.
  *
- * @beta
+ * @public
  */
 export declare const InferenceMode: {
     readonly PREFER_ON_DEVICE: "prefer_on_device";
@@ -426,13 +426,13 @@ export declare const InferenceMode: {
 /**
  * Determines whether inference happens on-device or in-cloud.
  *
- * @beta
+ * @public
  */
 export type InferenceMode = (typeof InferenceMode)[keyof typeof InferenceMode];
 /**
  * Indicates whether inference happened on-device or in-cloud.
  *
- * @beta
+ * @public
  */
 export declare const InferenceSource: {
     readonly ON_DEVICE: "on_device";
@@ -441,7 +441,7 @@ export declare const InferenceSource: {
 /**
  * Indicates whether inference happened on-device or in-cloud.
  *
- * @beta
+ * @public
  */
 export type InferenceSource = (typeof InferenceSource)[keyof typeof InferenceSource];
 /**

package/dist/esm/src/types/index.d.ts

@@ -22,5 +22,5 @@ export * from './error';
 export * from './schema';
 export * from './imagen';
 export * from './googleai';
-export { LanguageModelCreateOptions, LanguageModelCreateCoreOptions, LanguageModelExpected, LanguageModelMessage, LanguageModelMessageContent, LanguageModelMessageContentValue, LanguageModelMessageRole, LanguageModelMessageType, LanguageModelPromptOptions } from './language-model';
+export { LanguageModelCreateOptions, LanguageModelCreateCoreOptions, LanguageModelExpected, LanguageModelMessage, LanguageModelMessageContent, LanguageModelMessageContentValue, LanguageModelMessageRole, LanguageModelMessageType, LanguageModelPromptOptions, LanguageModelDownloadMonitor } from './language-model';
 export * from './chrome-adapter';

package/dist/esm/src/types/language-model.d.ts

@@ -40,7 +40,7 @@ export declare enum Availability {
 }
 /**
  * Configures the creation of an on-device language model session.
- * @beta
+ * @public
  */
 export interface LanguageModelCreateCoreOptions {
     /**
@@ -51,11 +51,41 @@ export interface LanguageModelCreateCoreOptions {
      * @deprecated
      */
     temperature?: number;
+    /**
+     * Defaults to image input and English text input
+     * if not overriden.
+     */
     expectedInputs?: LanguageModelExpected[];
+    /**
+     * Defaults to English text output if not overriden.
+     */
+    expectedOutputs?: LanguageModelExpected[];
+    /**
+     * The native download monitor provided by the Chrome API.
+     * This provides direct access to the monitor object and is
+     * only needed for advanced cases. For
+     * a simpler download monitoring interface, provide an
+     * `onDownloadProgress` callback
+     * to {@link GenerativeModel.initializeDeviceModel} instead.
+     */
+    monitor?: (monitor: LanguageModelDownloadMonitor) => void;
+}
+/**
+ * Interface representing the Chrome Prompt API's native
+ * download monitor object.
+ * @public
+ */
+export interface LanguageModelDownloadMonitor {
+    addEventListener: (eventType: 'downloadprogress', eventListener: (e: {
+        loaded: number;
+    }) => void) => void;
+    removeEventListener: (eventType: 'downloadprogress', eventListener: (e: {
+        loaded: number;
+    }) => void) => void;
 }
 /**
  * Configures the creation of an on-device language model session.
- * @beta
+ * @public
  */
 export interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
     signal?: AbortSignal;
@@ -63,26 +93,26 @@ export interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptio
 }
 /**
  * Options for an on-device language model prompt.
- * @beta
+ * @public
  */
 export interface LanguageModelPromptOptions {
     responseConstraint?: object;
 }
 /**
  * Options for the expected inputs for an on-device language model.
- * @beta
+ * @public
  */ export interface LanguageModelExpected {
     type: LanguageModelMessageType;
     languages?: string[];
 }
 /**
  * An on-device language model prompt.
- * @beta
+ * @public
  */
 export type LanguageModelPrompt = LanguageModelMessage[];
 /**
  * An on-device language model message.
- * @beta
+ * @public
  */
 export interface LanguageModelMessage {
     role: LanguageModelMessageRole;
@@ -90,7 +120,7 @@ export interface LanguageModelMessage {
 }
 /**
  * An on-device language model content object.
- * @beta
+ * @public
  */
 export interface LanguageModelMessageContent {
     type: LanguageModelMessageType;
@@ -98,16 +128,16 @@ export interface LanguageModelMessageContent {
 }
 /**
  * Allowable roles for on-device language model usage.
- * @beta
+ * @public
  */
 export type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
 /**
  * Allowable types for on-device language model messages.
- * @beta
+ * @public
  */
 export type LanguageModelMessageType = 'text' | 'image' | 'audio';
 /**
  * Content formats that can be provided as on-device message content.
- * @beta
+ * @public
  */
 export type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;

package/dist/esm/src/types/requests.d.ts

@@ -673,7 +673,7 @@ export interface RetrievalConfig {
 /**
  * Encapsulates configuration for on-device inference.
  *
- * @beta
+ * @public
  */
 export interface OnDeviceParams {
     createOptions?: LanguageModelCreateOptions;
@@ -681,7 +681,7 @@ export interface OnDeviceParams {
 }
 /**
  * Configures hybrid inference.
- * @beta
+ * @public
  */
 export interface HybridParams {
     /**

package/dist/esm/src/types/responses.d.ts

@@ -79,7 +79,7 @@ export interface EnhancedGenerateContentResponse extends GenerateContentResponse
     /**
      * Indicates whether inference happened on-device or in-cloud.
      *
-     * @beta
+     * @public
      */
     inferenceSource?: InferenceSource;
 }

package/dist/index.cjs.js

@@ -8,7 +8,7 @@ var util = require('@firebase/util');
 var logger$1 = require('@firebase/logger');
 
 var name = "@firebase/ai";
-var version = "2.12.0";
+var version = "2.13.0-20260526192810";
 
 /**
  * @license
@@ -447,7 +447,7 @@ const ResponseModality = {
  * cloud-hosted model. If not available, the SDK will fall back to an
  * on-device model.
  *
- * @beta
+ * @public
  */
 const InferenceMode = {
     'PREFER_ON_DEVICE': 'prefer_on_device',
@@ -458,7 +458,7 @@ const InferenceMode = {
 /**
  * Indicates whether inference happened on-device or in-cloud.
  *
- * @beta
+ * @public
  */
 const InferenceSource = {
     'ON_DEVICE': 'on_device',
@@ -1027,8 +1027,18 @@ var Availability;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-// Defaults to support image inputs for convenience.
-const defaultExpectedInputs = [{ type: 'image' }];
+// Defaults to English text. This can be overriden by user config.
+const defaultExpectedText = {
+    type: 'text',
+    languages: ['en']
+};
+const defaultExpectedInputs = [
+    defaultExpectedText,
+    { type: 'image' }
+];
+const defaultExpectedOutputs = [
+    defaultExpectedText
+];
 /**
  * Defines an inference "backend" that uses Chrome's on-device model,
  * and encapsulates logic for detecting when on-device inference is
@@ -1038,22 +1048,31 @@ class ChromeAdapterImpl {
     constructor(languageModelProvider, mode, onDeviceParams) {
         this.languageModelProvider = languageModelProvider;
         this.mode = mode;
-        this.isDownloading = false;
+        // Promise for on-device model download completion
+        this.downloadPromise = null;
         this.onDeviceParams = {
             createOptions: {
-                expectedInputs: defaultExpectedInputs
+                expectedInputs: defaultExpectedInputs,
+                expectedOutputs: defaultExpectedOutputs
             }
         };
         if (onDeviceParams) {
             this.onDeviceParams = onDeviceParams;
             if (!this.onDeviceParams.createOptions) {
                 this.onDeviceParams.createOptions = {
-                    expectedInputs: defaultExpectedInputs
+                    expectedInputs: defaultExpectedInputs,
+                    expectedOutputs: defaultExpectedOutputs
                 };
             }
-            else if (!this.onDeviceParams.createOptions.expectedInputs) {
-                this.onDeviceParams.createOptions.expectedInputs =
-                    defaultExpectedInputs;
+            else {
+                if (!this.onDeviceParams.createOptions.expectedInputs) {
+                    this.onDeviceParams.createOptions.expectedInputs =
+                        defaultExpectedInputs;
+                }
+                if (!this.onDeviceParams.createOptions.expectedOutputs) {
+                    this.onDeviceParams.createOptions.expectedOutputs =
+                        defaultExpectedOutputs;
+                }
             }
         }
     }
@@ -1064,7 +1083,7 @@ class ChromeAdapterImpl {
      *   the mode
      *   API existence
      *   prompt formatting
-     *   model availability, including triggering download if necessary
+     *   model availability
      *
      *
      * Pros: callers needn't be concerned with details of on-device availability.</p>
@@ -1081,8 +1100,7 @@ class ChromeAdapterImpl {
             logger.debug(`On-device inference unavailable because mode is "only_in_cloud".`);
             return false;
         }
-        // Triggers out-of-band download so model will eventually become available.
-        const availability = await this.downloadIfAvailable();
+        const availability = await this.languageModelProvider?.availability(this.onDeviceParams.createOptions);
         if (this.mode === InferenceMode.ONLY_ON_DEVICE) {
             // If it will never be available due to API inavailability, throw.
             if (availability === Availability.UNAVAILABLE) {
@@ -1090,9 +1108,13 @@ class ChromeAdapterImpl {
             }
             else if (availability === Availability.DOWNLOADABLE ||
                 availability === Availability.DOWNLOADING) {
-                // TODO(chholland): Better user experience during download - progress?
                 logger.debug(`Waiting for download of LanguageModel to complete.`);
-                await this.downloadPromise;
+                try {
+                    await this.downloadPromise;
+                }
+                catch (e) {
+                    throw new AIError(AIErrorCode.ERROR, e.message);
+                }
                 return true;
             }
             return true;
@@ -1169,31 +1191,44 @@ class ChromeAdapterImpl {
     /**
      * Encapsulates logic to get availability and download a model if one is downloadable.
      */
-    async downloadIfAvailable() {
+    async downloadIfAvailable(onDownloadProgress) {
         const availability = await this.languageModelProvider?.availability(this.onDeviceParams.createOptions);
-        if (availability === Availability.DOWNLOADABLE) {
-            this.download();
+        /**
+         * Download may have been automatically started by Chrome or other
+         * code, in which case we should still call create() to get a promise
+         * for when the download completes.
+         */
+        if (availability === Availability.DOWNLOADABLE ||
+            availability === Availability.DOWNLOADING) {
+            this.download(onDownloadProgress);
         }
         return availability;
     }
     /**
      * Triggers out-of-band download of an on-device model.
      *
-     * Chrome only downloads models as needed. Chrome knows a model is needed when code calls
-     * LanguageModel.create.
+     * Chrome may automatically begin a download on startup or
+     * it may trigger a download when code calls LanguageModel.create.
      *
      * Since Chrome manages the download, the SDK can only avoid redundant download requests by
      * tracking if a download has previously been requested.
      */
-    download() {
-        if (this.isDownloading) {
+    download(onDownloadProgress) {
+        if (this.downloadPromise) {
             return;
         }
-        this.isDownloading = true;
+        const options = { ...this.onDeviceParams.createOptions };
+        if (options && !options.monitor && onDownloadProgress) {
+            options.monitor = m => {
+                m.addEventListener('downloadprogress', e => {
+                    onDownloadProgress(e.loaded);
+                });
+            };
+        }
         this.downloadPromise = this.languageModelProvider
-            ?.create(this.onDeviceParams.createOptions)
+            ?.create(options)
             .finally(() => {
-            this.isDownloading = false;
+            this.downloadPromise = null;
         });
     }
     /**
@@ -1248,6 +1283,13 @@ class ChromeAdapterImpl {
         if (!this.languageModelProvider) {
             throw new AIError(AIErrorCode.UNSUPPORTED, 'Chrome AI requested for unsupported browser version.');
         }
+        /**
+         * Note: `create()` will trigger a download as a side effect if
+         * a model is not downloaded or downloading, but this specific
+         * create() call should not be relied on for the download. The download
+         * should be triggered explicitly by the user in
+         * GenerativeModel.initializeDeviceModel().
+         */
         const newSession = await this.languageModelProvider.create(this.onDeviceParams.createOptions);
         if (this.oldSession) {
             this.oldSession.destroy();
@@ -2439,7 +2481,9 @@ async function callCloudOrDevice(request, chromeAdapter, onDeviceCall, inCloudCa
                 };
             }
             catch (e) {
-                if (e instanceof AIError && errorsCausingFallback.includes(e.code)) {
+                if (e instanceof AIError &&
+                    errorsCausingFallback.includes(e.code) &&
+                    (await chromeAdapter.isAvailable(request))) {
                     return {
                         response: await onDeviceCall(),
                         inferenceSource: InferenceSource.ON_DEVICE
@@ -2766,7 +2810,9 @@ class ChatSessionBase {
                 else {
                     formattedContent = formatNewContent(request);
                 }
-                const formattedRequest = this._formatRequest(formattedContent, tempHistory);
+                const formattedRequest = this._formatRequest(formattedContent, [
+                    ...tempHistory
+                ]);
                 tempHistory.push(formattedContent);
                 const result = await this._callGenerateContent(formattedRequest, singleRequestOptions);
                 if (result) {
@@ -2836,8 +2882,10 @@ class ChatSessionBase {
                 else {
                     formattedContent = formatNewContent(request);
                 }
+                const formattedRequest = this._formatRequest(formattedContent, [
+                    ...tempHistory
+                ]);
                 tempHistory.push(formattedContent);
-                const formattedRequest = this._formatRequest(formattedContent, tempHistory);
                 result = await this._callGenerateContentStream(formattedRequest, singleRequestOptions);
                 functionCalls = this._getCallableFunctionCalls(result.firstValue);
                 if (functionCalls &&
@@ -3225,6 +3273,52 @@ class GenerativeModel extends AIModel {
         this.systemInstruction = formatSystemInstruction(modelParams.systemInstruction);
         this.requestOptions = requestOptions || {};
     }
+    /**
+     * Initializes on-device models.
+     *
+     * @remarks
+     * This may trigger a download on first
+     * use. Wait for this promise to complete before calling inference
+     * methods if you want to ensure the device models are ready before
+     * any calls. Calling inference methods before the device is ready
+     * will result in a cloud fallback if `inferenceMode` is set to
+     * `PREFER_ON_DEVICE`, and an error if set to `ONLY_ON_DEVICE`.
+     *
+     * IMPORTANT: This call must be made on or after a user has interacted
+     * with the page (for example, through a button click or key press).
+     * If it is called without a user interaction, and it requires a download,
+     * this will cause an error.
+     *
+     * See the
+     * {@link https://developer.chrome.com/docs/ai/prompt-api#use_the_prompt_api | Prompt API docs }
+     * for more details on this requirement.
+     *
+     * @param onDownloadProgress A callback called repeatedly as the
+     * download progresses that provides a `progressValue` between 0
+     * and 1 representing how much of the download is complete. This
+     * will be ignored if `monitor` was populated in
+     * {@link LanguageModelCreateOptions}.
+     *
+     * @public
+     */
+    async initializeDeviceModel(onDownloadProgress) {
+        if (!this.chromeAdapter ||
+            this.chromeAdapter.mode === InferenceMode.ONLY_IN_CLOUD) {
+            return;
+        }
+        const availability = await this.chromeAdapter.downloadIfAvailable(onDownloadProgress);
+        if (availability === Availability.UNAVAILABLE) {
+            const notEnabledError = new AIError(AIErrorCode.API_NOT_ENABLED, 'Local LanguageModel API not available in this environment.');
+            if (this.chromeAdapter.mode === InferenceMode.ONLY_ON_DEVICE) {
+                throw notEnabledError;
+            }
+            else {
+                // No reason to throw if not in ONLY_ON_DEVICE mode.
+                logger.debug(notEnabledError.message);
+            }
+        }
+        await this.chromeAdapter.downloadPromise;
+    }
     /**
      * Makes a single non-streaming call to the model
      * and returns an object containing a single {@link GenerateContentResponse}.