@firebase/ai 2.0.0 → 2.1.0

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.0.0";
+var version = "2.1.0";
 
 /**
  * @license
@@ -33,6 +33,10 @@ const DEFAULT_API_VERSION = 'v1beta';
 const PACKAGE_VERSION = version;
 const LANGUAGE_TAG = 'gl-js';
 const DEFAULT_FETCH_TIMEOUT_MS = 180 * 1000;
+/**
+ * Defines the name of the default in-cloud model to use for hybrid inference.
+ */
+const DEFAULT_HYBRID_IN_CLOUD_MODEL = 'gemini-2.0-flash-lite';
 
 /**
  * @license
@@ -88,7 +92,7 @@ const HarmBlockThreshold = {
     BLOCK_NONE: 'BLOCK_NONE',
     /**
      * All content will be allowed. This is the same as `BLOCK_NONE`, but the metadata corresponding
-     * to the {@link HarmCategory} will not be present in the response.
+     * to the {@link (HarmCategory:type)} will not be present in the response.
      */
     OFF: 'OFF'
 };
@@ -291,6 +295,16 @@ const ResponseModality = {
      */
     IMAGE: 'IMAGE'
 };
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Determines whether inference happens on-device or in-cloud.
+ * @public
+ */
+const InferenceMode = {
+    'PREFER_ON_DEVICE': 'prefer_on_device',
+    'ONLY_ON_DEVICE': 'only_on_device',
+    'ONLY_IN_CLOUD': 'only_in_cloud'
+};
 
 /**
  * @license
@@ -464,7 +478,7 @@ const ImagenPersonFilterLevel = {
  * To specify an aspect ratio for generated images, set the `aspectRatio` property in your
  * {@link ImagenGenerationConfig}.
  *
- * See the the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation }
+ * See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation }
  * for more details and examples of the supported aspect ratios.
  *
  * @beta
@@ -1664,20 +1678,38 @@ function aggregateResponses(responses) {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-async function generateContentStream(apiSettings, model, params, requestOptions) {
+async function generateContentStreamOnCloud(apiSettings, model, params, requestOptions) {
     if (apiSettings.backend.backendType === BackendType.GOOGLE_AI) {
         params = mapGenerateContentRequest(params);
     }
-    const response = await makeRequest(model, Task.STREAM_GENERATE_CONTENT, apiSettings, 
+    return makeRequest(model, Task.STREAM_GENERATE_CONTENT, apiSettings, 
     /* stream */ true, JSON.stringify(params), requestOptions);
+}
+async function generateContentStream(apiSettings, model, params, chromeAdapter, requestOptions) {
+    let response;
+    if (chromeAdapter && (await chromeAdapter.isAvailable(params))) {
+        response = await chromeAdapter.generateContentStream(params);
+    }
+    else {
+        response = await generateContentStreamOnCloud(apiSettings, model, params, requestOptions);
+    }
     return processStream(response, apiSettings); // TODO: Map streaming responses
 }
-async function generateContent(apiSettings, model, params, requestOptions) {
+async function generateContentOnCloud(apiSettings, model, params, requestOptions) {
     if (apiSettings.backend.backendType === BackendType.GOOGLE_AI) {
         params = mapGenerateContentRequest(params);
     }
-    const response = await makeRequest(model, Task.GENERATE_CONTENT, apiSettings, 
+    return makeRequest(model, Task.GENERATE_CONTENT, apiSettings, 
     /* stream */ false, JSON.stringify(params), requestOptions);
+}
+async function generateContent(apiSettings, model, params, chromeAdapter, requestOptions) {
+    let response;
+    if (chromeAdapter && (await chromeAdapter.isAvailable(params))) {
+        response = await chromeAdapter.generateContent(params);
+    }
+    else {
+        response = await generateContentOnCloud(apiSettings, model, params, requestOptions);
+    }
     const generateContentResponse = await processGenerateContentResponse(response, apiSettings);
     const enhancedResponse = createEnhancedContentResponse(generateContentResponse);
     return {
@@ -1934,8 +1966,9 @@ const SILENT_ERROR = 'SILENT_ERROR';
  * @public
  */
 class ChatSession {
-    constructor(apiSettings, model, params, requestOptions) {
+    constructor(apiSettings, model, chromeAdapter, params, requestOptions) {
         this.model = model;
+        this.chromeAdapter = chromeAdapter;
         this.params = params;
         this.requestOptions = requestOptions;
         this._history = [];
@@ -1973,7 +2006,7 @@ class ChatSession {
         let finalResult = {};
         // Add onto the chain.
         this._sendPromise = this._sendPromise
-            .then(() => generateContent(this._apiSettings, this.model, generateContentRequest, this.requestOptions))
+            .then(() => generateContent(this._apiSettings, this.model, generateContentRequest, this.chromeAdapter, this.requestOptions))
             .then(result => {
             if (result.response.candidates &&
                 result.response.candidates.length > 0) {
@@ -2012,7 +2045,7 @@ class ChatSession {
             systemInstruction: this.params?.systemInstruction,
             contents: [...this._history, newContent]
         };
-        const streamPromise = generateContentStream(this._apiSettings, this.model, generateContentRequest, this.requestOptions);
+        const streamPromise = generateContentStream(this._apiSettings, this.model, generateContentRequest, this.chromeAdapter, this.requestOptions);
         // Add onto the chain.
         this._sendPromise = this._sendPromise
             .then(() => streamPromise)
@@ -2069,7 +2102,7 @@ class ChatSession {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-async function countTokens(apiSettings, model, params, requestOptions) {
+async function countTokensOnCloud(apiSettings, model, params, requestOptions) {
     let body = '';
     if (apiSettings.backend.backendType === BackendType.GOOGLE_AI) {
         const mappedParams = mapCountTokensRequest(params, model);
@@ -2081,6 +2114,12 @@ async function countTokens(apiSettings, model, params, requestOptions) {
     const response = await makeRequest(model, Task.COUNT_TOKENS, apiSettings, false, body, requestOptions);
     return response.json();
 }
+async function countTokens(apiSettings, model, params, chromeAdapter, requestOptions) {
+    if (chromeAdapter && (await chromeAdapter.isAvailable(params))) {
+        return (await chromeAdapter.countTokens(params)).json();
+    }
+    return countTokensOnCloud(apiSettings, model, params, requestOptions);
+}
 
 /**
  * @license
@@ -2103,8 +2142,9 @@ async function countTokens(apiSettings, model, params, requestOptions) {
  * @public
  */
 class GenerativeModel extends AIModel {
-    constructor(ai, modelParams, requestOptions) {
+    constructor(ai, modelParams, requestOptions, chromeAdapter) {
         super(ai, modelParams.model);
+        this.chromeAdapter = chromeAdapter;
         this.generationConfig = modelParams.generationConfig || {};
         this.safetySettings = modelParams.safetySettings || [];
         this.tools = modelParams.tools;
@@ -2125,7 +2165,7 @@ class GenerativeModel extends AIModel {
             toolConfig: this.toolConfig,
             systemInstruction: this.systemInstruction,
             ...formattedParams
-        }, this.requestOptions);
+        }, this.chromeAdapter, this.requestOptions);
     }
     /**
      * Makes a single streaming call to the model
@@ -2142,14 +2182,14 @@ class GenerativeModel extends AIModel {
             toolConfig: this.toolConfig,
             systemInstruction: this.systemInstruction,
             ...formattedParams
-        }, this.requestOptions);
+        }, this.chromeAdapter, this.requestOptions);
     }
     /**
      * Gets a new {@link ChatSession} instance which can be used for
      * multi-turn chats.
      */
     startChat(startChatParams) {
-        return new ChatSession(this._apiSettings, this.model, {
+        return new ChatSession(this._apiSettings, this.model, this.chromeAdapter, {
             tools: this.tools,
             toolConfig: this.toolConfig,
             systemInstruction: this.systemInstruction,
@@ -2168,7 +2208,7 @@ class GenerativeModel extends AIModel {
      */
     async countTokens(request) {
         const formattedParams = formatGenerateContentInput(request);
-        return countTokens(this._apiSettings, this.model, formattedParams);
+        return countTokens(this._apiSettings, this.model, formattedParams, this.chromeAdapter);
     }
 }
 
@@ -2286,6 +2326,290 @@ class ImagenModel extends AIModel {
     }
 }
 
+/**
+ * @internal
+ */
+var Availability;
+(function (Availability) {
+    Availability["UNAVAILABLE"] = "unavailable";
+    Availability["DOWNLOADABLE"] = "downloadable";
+    Availability["DOWNLOADING"] = "downloading";
+    Availability["AVAILABLE"] = "available";
+})(Availability || (Availability = {}));
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Defines an inference "backend" that uses Chrome's on-device model,
+ * and encapsulates logic for detecting when on-device inference is
+ * possible.
+ */
+class ChromeAdapterImpl {
+    constructor(languageModelProvider, mode, onDeviceParams = {
+        createOptions: {
+            // Defaults to support image inputs for convenience.
+            expectedInputs: [{ type: 'image' }]
+        }
+    }) {
+        this.languageModelProvider = languageModelProvider;
+        this.mode = mode;
+        this.onDeviceParams = onDeviceParams;
+        this.isDownloading = false;
+    }
+    /**
+     * Checks if a given request can be made on-device.
+     *
+     * <ol>Encapsulates a few concerns:
+     *   <li>the mode</li>
+     *   <li>API existence</li>
+     *   <li>prompt formatting</li>
+     *   <li>model availability, including triggering download if necessary</li>
+     * </ol>
+     *
+     * <p>Pros: callers needn't be concerned with details of on-device availability.</p>
+     * <p>Cons: this method spans a few concerns and splits request validation from usage.
+     * If instance variables weren't already part of the API, we could consider a better
+     * separation of concerns.</p>
+     */
+    async isAvailable(request) {
+        if (!this.mode) {
+            logger.debug(`On-device inference unavailable because mode is undefined.`);
+            return false;
+        }
+        if (this.mode === InferenceMode.ONLY_IN_CLOUD) {
+            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();
+        if (this.mode === InferenceMode.ONLY_ON_DEVICE) {
+            // If it will never be available due to API inavailability, throw.
+            if (availability === Availability.UNAVAILABLE) {
+                throw new AIError(AIErrorCode.API_NOT_ENABLED, 'Local LanguageModel API not available in this environment.');
+            }
+            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;
+                return true;
+            }
+            return true;
+        }
+        // Applies prefer_on_device logic.
+        if (availability !== Availability.AVAILABLE) {
+            logger.debug(`On-device inference unavailable because availability is "${availability}".`);
+            return false;
+        }
+        if (!ChromeAdapterImpl.isOnDeviceRequest(request)) {
+            logger.debug(`On-device inference unavailable because request is incompatible.`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Generates content on device.
+     *
+     * <p>This is comparable to {@link GenerativeModel.generateContent} for generating content in
+     * Cloud.</p>
+     * @param request - a standard Firebase AI {@link GenerateContentRequest}
+     * @returns {@link Response}, so we can reuse common response formatting.
+     */
+    async generateContent(request) {
+        const session = await this.createSession();
+        const contents = await Promise.all(request.contents.map(ChromeAdapterImpl.toLanguageModelMessage));
+        const text = await session.prompt(contents, this.onDeviceParams.promptOptions);
+        return ChromeAdapterImpl.toResponse(text);
+    }
+    /**
+     * Generates content stream on device.
+     *
+     * <p>This is comparable to {@link GenerativeModel.generateContentStream} for generating content in
+     * Cloud.</p>
+     * @param request - a standard Firebase AI {@link GenerateContentRequest}
+     * @returns {@link Response}, so we can reuse common response formatting.
+     */
+    async generateContentStream(request) {
+        const session = await this.createSession();
+        const contents = await Promise.all(request.contents.map(ChromeAdapterImpl.toLanguageModelMessage));
+        const stream = session.promptStreaming(contents, this.onDeviceParams.promptOptions);
+        return ChromeAdapterImpl.toStreamResponse(stream);
+    }
+    async countTokens(_request) {
+        throw new AIError(AIErrorCode.REQUEST_ERROR, 'Count Tokens is not yet available for on-device model.');
+    }
+    /**
+     * Asserts inference for the given request can be performed by an on-device model.
+     */
+    static isOnDeviceRequest(request) {
+        // Returns false if the prompt is empty.
+        if (request.contents.length === 0) {
+            logger.debug('Empty prompt rejected for on-device inference.');
+            return false;
+        }
+        for (const content of request.contents) {
+            if (content.role === 'function') {
+                logger.debug(`"Function" role rejected for on-device inference.`);
+                return false;
+            }
+            // Returns false if request contains an image with an unsupported mime type.
+            for (const part of content.parts) {
+                if (part.inlineData &&
+                    ChromeAdapterImpl.SUPPORTED_MIME_TYPES.indexOf(part.inlineData.mimeType) === -1) {
+                    logger.debug(`Unsupported mime type "${part.inlineData.mimeType}" rejected for on-device inference.`);
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Encapsulates logic to get availability and download a model if one is downloadable.
+     */
+    async downloadIfAvailable() {
+        const availability = await this.languageModelProvider?.availability(this.onDeviceParams.createOptions);
+        if (availability === Availability.DOWNLOADABLE) {
+            this.download();
+        }
+        return availability;
+    }
+    /**
+     * Triggers out-of-band download of an on-device model.
+     *
+     * <p>Chrome only downloads models as needed. Chrome knows a model is needed when code calls
+     * LanguageModel.create.</p>
+     *
+     * <p>Since Chrome manages the download, the SDK can only avoid redundant download requests by
+     * tracking if a download has previously been requested.</p>
+     */
+    download() {
+        if (this.isDownloading) {
+            return;
+        }
+        this.isDownloading = true;
+        this.downloadPromise = this.languageModelProvider
+            ?.create(this.onDeviceParams.createOptions)
+            .finally(() => {
+            this.isDownloading = false;
+        });
+    }
+    /**
+     * Converts Firebase AI {@link Content} object to a Chrome {@link LanguageModelMessage} object.
+     */
+    static async toLanguageModelMessage(content) {
+        const languageModelMessageContents = await Promise.all(content.parts.map(ChromeAdapterImpl.toLanguageModelMessageContent));
+        return {
+            role: ChromeAdapterImpl.toLanguageModelMessageRole(content.role),
+            content: languageModelMessageContents
+        };
+    }
+    /**
+     * Converts a Firebase AI Part object to a Chrome LanguageModelMessageContent object.
+     */
+    static async toLanguageModelMessageContent(part) {
+        if (part.text) {
+            return {
+                type: 'text',
+                value: part.text
+            };
+        }
+        else if (part.inlineData) {
+            const formattedImageContent = await fetch(`data:${part.inlineData.mimeType};base64,${part.inlineData.data}`);
+            const imageBlob = await formattedImageContent.blob();
+            const imageBitmap = await createImageBitmap(imageBlob);
+            return {
+                type: 'image',
+                value: imageBitmap
+            };
+        }
+        throw new AIError(AIErrorCode.REQUEST_ERROR, `Processing of this Part type is not currently supported.`);
+    }
+    /**
+     * Converts a Firebase AI {@link Role} string to a {@link LanguageModelMessageRole} string.
+     */
+    static toLanguageModelMessageRole(role) {
+        // Assumes 'function' rule has been filtered by isOnDeviceRequest
+        return role === 'model' ? 'assistant' : 'user';
+    }
+    /**
+     * Abstracts Chrome session creation.
+     *
+     * <p>Chrome uses a multi-turn session for all inference. Firebase AI uses single-turn for all
+     * inference. To map the Firebase AI API to Chrome's API, the SDK creates a new session for all
+     * inference.</p>
+     *
+     * <p>Chrome will remove a model from memory if it's no longer in use, so this method ensures a
+     * new session is created before an old session is destroyed.</p>
+     */
+    async createSession() {
+        if (!this.languageModelProvider) {
+            throw new AIError(AIErrorCode.UNSUPPORTED, 'Chrome AI requested for unsupported browser version.');
+        }
+        const newSession = await this.languageModelProvider.create(this.onDeviceParams.createOptions);
+        if (this.oldSession) {
+            this.oldSession.destroy();
+        }
+        // Holds session reference, so model isn't unloaded from memory.
+        this.oldSession = newSession;
+        return newSession;
+    }
+    /**
+     * Formats string returned by Chrome as a {@link Response} returned by Firebase AI.
+     */
+    static toResponse(text) {
+        return {
+            json: async () => ({
+                candidates: [
+                    {
+                        content: {
+                            parts: [{ text }]
+                        }
+                    }
+                ]
+            })
+        };
+    }
+    /**
+     * Formats string stream returned by Chrome as SSE returned by Firebase AI.
+     */
+    static toStreamResponse(stream) {
+        const encoder = new TextEncoder();
+        return {
+            body: stream.pipeThrough(new TransformStream({
+                transform(chunk, controller) {
+                    const json = JSON.stringify({
+                        candidates: [
+                            {
+                                content: {
+                                    role: 'model',
+                                    parts: [{ text: chunk }]
+                                }
+                            }
+                        ]
+                    });
+                    controller.enqueue(encoder.encode(`data: ${json}\n\n`));
+                }
+            }))
+        };
+    }
+}
+// Visible for testing
+ChromeAdapterImpl.SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png'];
+
 /**
  * @license
  * Copyright 2024 Google LLC
@@ -2653,10 +2977,26 @@ function getAI(app$1 = app.getApp(), options = { backend: new GoogleAIBackend()
  * @public
  */
 function getGenerativeModel(ai, modelParams, requestOptions) {
-    if (!modelParams.model) {
+    // Uses the existence of HybridParams.mode to clarify the type of the modelParams input.
+    const hybridParams = modelParams;
+    let inCloudParams;
+    if (hybridParams.mode) {
+        inCloudParams = hybridParams.inCloudParams || {
+            model: DEFAULT_HYBRID_IN_CLOUD_MODEL
+        };
+    }
+    else {
+        inCloudParams = modelParams;
+    }
+    if (!inCloudParams.model) {
         throw new AIError(AIErrorCode.NO_MODEL, `Must provide a model name. Example: getGenerativeModel({ model: 'my-model-name' })`);
     }
-    return new GenerativeModel(ai, modelParams, requestOptions);
+    let chromeAdapter;
+    // Do not initialize a ChromeAdapter if we are not in hybrid mode.
+    if (typeof window !== 'undefined' && hybridParams.mode) {
+        chromeAdapter = new ChromeAdapterImpl(window.LanguageModel, hybridParams.mode, hybridParams.onDeviceParams);
+    }
+    return new GenerativeModel(ai, inCloudParams, requestOptions, chromeAdapter);
 }
 /**
  * Returns an {@link ImagenModel} class with methods for using Imagen.
@@ -2726,6 +3066,7 @@ exports.ImagenImageFormat = ImagenImageFormat;
 exports.ImagenModel = ImagenModel;
 exports.ImagenPersonFilterLevel = ImagenPersonFilterLevel;
 exports.ImagenSafetyFilterLevel = ImagenSafetyFilterLevel;
+exports.InferenceMode = InferenceMode;
 exports.IntegerSchema = IntegerSchema;
 exports.Modality = Modality;
 exports.NumberSchema = NumberSchema;