@firebase/ai 2.12.0 → 2.13.0-20260526192810

package/dist/esm/index.esm.js

@@ -4,7 +4,7 @@ import { FirebaseError, Deferred, getModularInstance } from '@firebase/util';
 import { Logger } from '@firebase/logger';
 
 var name = "@firebase/ai";
-var version = "2.12.0";
+var version = "2.13.0-20260526192810";
 
 /**
  * @license
@@ -443,7 +443,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',
@@ -454,7 +454,7 @@ const InferenceMode = {
 /**
  * Indicates whether inference happened on-device or in-cloud.
  *
- * @beta
+ * @public
  */
 const InferenceSource = {
     'ON_DEVICE': 'on_device',
@@ -1023,8 +1023,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
@@ -1034,22 +1044,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;
+                }
             }
         }
     }
@@ -1060,7 +1079,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>
@@ -1077,8 +1096,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) {
@@ -1086,9 +1104,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;
@@ -1165,31 +1187,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;
         });
     }
     /**
@@ -1244,6 +1279,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();
@@ -2435,7 +2477,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
@@ -2762,7 +2806,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) {
@@ -2832,8 +2878,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 &&
@@ -3221,6 +3269,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}.