@firebase/ai 2.2.1 → 2.3.0-caching-fdc.9f17eac6e

package/dist/index.node.cjs.js

@@ -8,7 +8,7 @@ var util = require('@firebase/util');
 var logger$1 = require('@firebase/logger');
 
 var name = "@firebase/ai";
-var version = "2.2.1";
+var version = "2.3.0-caching-fdc.9f17eac6e";
 
 /**
  * @license
@@ -301,14 +301,51 @@ const ResponseModality = {
     AUDIO: 'AUDIO'
 };
 /**
- * <b>(EXPERIMENTAL)</b>
  * Determines whether inference happens on-device or in-cloud.
- * @public
+ *
+ * @remarks
+ * <b>PREFER_ON_DEVICE:</b> Attempt to make inference calls using an
+ * on-device model. If on-device inference is not available, the SDK
+ * will fall back to using a cloud-hosted model.
+ * <br/>
+ * <b>ONLY_ON_DEVICE:</b> Only attempt to make inference calls using an
+ * on-device model. The SDK will not fall back to a cloud-hosted model.
+ * If on-device inference is not available, inference methods will throw.
+ * <br/>
+ * <b>ONLY_IN_CLOUD:</b> Only attempt to make inference calls using a
+ * cloud-hosted model. The SDK will not fall back to an on-device model.
+ * <br/>
+ * <b>PREFER_IN_CLOUD:</b> Attempt to make inference calls to a
+ * cloud-hosted model. If not available, the SDK will fall back to an
+ * on-device model.
+ *
+ * @beta
  */
 const InferenceMode = {
     'PREFER_ON_DEVICE': 'prefer_on_device',
     'ONLY_ON_DEVICE': 'only_on_device',
-    'ONLY_IN_CLOUD': 'only_in_cloud'
+    'ONLY_IN_CLOUD': 'only_in_cloud',
+    'PREFER_IN_CLOUD': 'prefer_in_cloud'
+};
+/**
+ * Represents the result of the code execution.
+ *
+ * @beta
+ */
+const Outcome = {
+    UNSPECIFIED: 'OUTCOME_UNSPECIFIED',
+    OK: 'OUTCOME_OK',
+    FAILED: 'OUTCOME_FAILED',
+    DEADLINE_EXCEEDED: 'OUTCOME_DEADLINE_EXCEEDED'
+};
+/**
+ * The programming language of the code.
+ *
+ * @beta
+ */
+const Language = {
+    UNSPECIFIED: 'LANGUAGE_UNSPECIFIED',
+    PYTHON: 'PYTHON'
 };
 
 /**
@@ -327,6 +364,45 @@ const InferenceMode = {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * The status of a URL retrieval.
+ *
+ * @remarks
+ * <b>URL_RETRIEVAL_STATUS_UNSPECIFIED:</b> Unspecified retrieval status.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_UNSAFE:</b> The URL retrieval failed because the content is unsafe.
+ * <br/>
+ *
+ * @beta
+ */
+const URLRetrievalStatus = {
+    /**
+     * Unspecified retrieval status.
+     */
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: 'URL_RETRIEVAL_STATUS_UNSPECIFIED',
+    /**
+     * The URL retrieval was successful.
+     */
+    URL_RETRIEVAL_STATUS_SUCCESS: 'URL_RETRIEVAL_STATUS_SUCCESS',
+    /**
+     * The URL retrieval failed.
+     */
+    URL_RETRIEVAL_STATUS_ERROR: 'URL_RETRIEVAL_STATUS_ERROR',
+    /**
+     * The URL retrieval failed because the content is behind a paywall.
+     */
+    URL_RETRIEVAL_STATUS_PAYWALL: 'URL_RETRIEVAL_STATUS_PAYWALL',
+    /**
+     * The URL retrieval failed because the content is unsafe.
+     */
+    URL_RETRIEVAL_STATUS_UNSAFE: 'URL_RETRIEVAL_STATUS_UNSAFE'
+};
 /**
  * The types of responses that can be returned by {@link LiveSession.receive}.
  *
@@ -1520,7 +1596,7 @@ function mapGenerateContentCandidates(candidates) {
             // videoMetadata is not supported.
             // Throw early since developers may send a long video as input and only expect to pay
             // for inference on a small portion of the video.
-            if (candidate.content?.parts.some(part => part?.videoMetadata)) {
+            if (candidate.content?.parts?.some(part => part?.videoMetadata)) {
                 throw new AIError(AIErrorCode.UNSUPPORTED, 'Part.videoMetadata is not supported in the Gemini Developer API. Please remove this property.');
             }
             const mappedCandidate = {
@@ -1530,7 +1606,8 @@ function mapGenerateContentCandidates(candidates) {
                 finishMessage: candidate.finishMessage,
                 safetyRatings: mappedSafetyRatings,
                 citationMetadata,
-                groundingMetadata: candidate.groundingMetadata
+                groundingMetadata: candidate.groundingMetadata,
+                urlContextMetadata: candidate.urlContextMetadata
             };
             mappedCandidates.push(mappedCandidate);
         });
@@ -1621,6 +1698,14 @@ async function* generateResponseSequence(stream, apiSettings) {
         else {
             enhancedResponse = createEnhancedContentResponse(value);
         }
+        const firstCandidate = enhancedResponse.candidates?.[0];
+        // Don't yield a response with no useful data for the developer.
+        if (!firstCandidate?.content?.parts &&
+            !firstCandidate?.finishReason &&
+            !firstCandidate?.citationMetadata &&
+            !firstCandidate?.urlContextMetadata) {
+            continue;
+        }
         yield enhancedResponse;
     }
 }
@@ -1700,36 +1785,43 @@ function aggregateResponses(responses) {
                     candidate.safetyRatings;
                 aggregatedResponse.candidates[i].groundingMetadata =
                     candidate.groundingMetadata;
+                // The urlContextMetadata object is defined in the first chunk of the response stream.
+                // In all subsequent chunks, the urlContextMetadata object will be undefined. We need to
+                // make sure that we don't overwrite the first value urlContextMetadata object with undefined.
+                // FIXME: What happens if we receive a second, valid urlContextMetadata object?
+                const urlContextMetadata = candidate.urlContextMetadata;
+                if (typeof urlContextMetadata === 'object' &&
+                    urlContextMetadata !== null &&
+                    Object.keys(urlContextMetadata).length > 0) {
+                    aggregatedResponse.candidates[i].urlContextMetadata =
+                        urlContextMetadata;
+                }
                 /**
                  * Candidates should always have content and parts, but this handles
                  * possible malformed responses.
                  */
-                if (candidate.content && candidate.content.parts) {
+                if (candidate.content) {
+                    // Skip a candidate without parts.
+                    if (!candidate.content.parts) {
+                        continue;
+                    }
                     if (!aggregatedResponse.candidates[i].content) {
                         aggregatedResponse.candidates[i].content = {
                             role: candidate.content.role || 'user',
                             parts: []
                         };
                     }
-                    const newPart = {};
                     for (const part of candidate.content.parts) {
-                        if (part.text !== undefined) {
-                            // The backend can send empty text parts. If these are sent back
-                            // (e.g. in chat history), the backend will respond with an error.
-                            // To prevent this, ignore empty text parts.
-                            if (part.text === '') {
-                                continue;
-                            }
-                            newPart.text = part.text;
+                        const newPart = { ...part };
+                        // The backend can send empty text parts. If these are sent back
+                        // (e.g. in chat history), the backend will respond with an error.
+                        // To prevent this, ignore empty text parts.
+                        if (part.text === '') {
+                            continue;
                         }
-                        if (part.functionCall) {
-                            newPart.functionCall = part.functionCall;
+                        if (Object.keys(newPart).length > 0) {
+                            aggregatedResponse.candidates[i].content.parts.push(newPart);
                         }
-                        if (Object.keys(newPart).length === 0) {
-                            throw new AIError(AIErrorCode.INVALID_CONTENT, 'Part should have at least one property, but there are none. This is likely caused ' +
-                                'by a malformed response from the backend.');
-                        }
-                        aggregatedResponse.candidates[i].content.parts.push(newPart);
                     }
                 }
             }
@@ -1738,6 +1830,72 @@ function aggregateResponses(responses) {
     return aggregatedResponse;
 }
 
+/**
+ * @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.
+ */
+const errorsCausingFallback = [
+    // most network errors
+    AIErrorCode.FETCH_ERROR,
+    // fallback code for all other errors in makeRequest
+    AIErrorCode.ERROR,
+    // error due to API not being enabled in project
+    AIErrorCode.API_NOT_ENABLED
+];
+/**
+ * Dispatches a request to the appropriate backend (on-device or in-cloud)
+ * based on the inference mode.
+ *
+ * @param request - The request to be sent.
+ * @param chromeAdapter - The on-device model adapter.
+ * @param onDeviceCall - The function to call for on-device inference.
+ * @param inCloudCall - The function to call for in-cloud inference.
+ * @returns The response from the backend.
+ */
+async function callCloudOrDevice(request, chromeAdapter, onDeviceCall, inCloudCall) {
+    if (!chromeAdapter) {
+        return inCloudCall();
+    }
+    switch (chromeAdapter.mode) {
+        case InferenceMode.ONLY_ON_DEVICE:
+            if (await chromeAdapter.isAvailable(request)) {
+                return onDeviceCall();
+            }
+            throw new AIError(AIErrorCode.UNSUPPORTED, 'Inference mode is ONLY_ON_DEVICE, but an on-device model is not available.');
+        case InferenceMode.ONLY_IN_CLOUD:
+            return inCloudCall();
+        case InferenceMode.PREFER_IN_CLOUD:
+            try {
+                return await inCloudCall();
+            }
+            catch (e) {
+                if (e instanceof AIError && errorsCausingFallback.includes(e.code)) {
+                    return onDeviceCall();
+                }
+                throw e;
+            }
+        case InferenceMode.PREFER_ON_DEVICE:
+            if (await chromeAdapter.isAvailable(request)) {
+                return onDeviceCall();
+            }
+            return inCloudCall();
+        default:
+            throw new AIError(AIErrorCode.ERROR, `Unexpected infererence mode: ${chromeAdapter.mode}`);
+    }
+}
+
 /**
  * @license
  * Copyright 2024 Google LLC
@@ -1762,13 +1920,7 @@ async function generateContentStreamOnCloud(apiSettings, model, params, requestO
     /* 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);
-    }
+    const response = await callCloudOrDevice(params, chromeAdapter, () => chromeAdapter.generateContentStream(params), () => generateContentStreamOnCloud(apiSettings, model, params, requestOptions));
     return processStream(response, apiSettings); // TODO: Map streaming responses
 }
 async function generateContentOnCloud(apiSettings, model, params, requestOptions) {
@@ -1779,13 +1931,7 @@ async function generateContentOnCloud(apiSettings, model, params, requestOptions
     /* 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 response = await callCloudOrDevice(params, chromeAdapter, () => chromeAdapter.generateContent(params), () => generateContentOnCloud(apiSettings, model, params, requestOptions));
     const generateContentResponse = await processGenerateContentResponse(response, apiSettings);
     const enhancedResponse = createEnhancedContentResponse(generateContentResponse);
     return {
@@ -1995,7 +2141,9 @@ function validateChatHistory(history) {
             functionCall: 0,
             functionResponse: 0,
             thought: 0,
-            thoughtSignature: 0
+            thoughtSignature: 0,
+            executableCode: 0,
+            codeExecutionResult: 0
         };
         for (const part of parts) {
             for (const key of VALID_PART_FIELDS) {
@@ -2196,8 +2344,8 @@ async function countTokensOnCloud(apiSettings, model, params, requestOptions) {
     return response.json();
 }
 async function countTokens(apiSettings, model, params, chromeAdapter, requestOptions) {
-    if (chromeAdapter && (await chromeAdapter.isAvailable(params))) {
-        return (await chromeAdapter.countTokens(params)).json();
+    if (chromeAdapter?.mode === InferenceMode.ONLY_ON_DEVICE) {
+        throw new AIError(AIErrorCode.UNSUPPORTED, 'countTokens() is not supported for on-device models.');
     }
     return countTokensOnCloud(apiSettings, model, params, requestOptions);
 }
@@ -2379,6 +2527,25 @@ class LiveSession {
             this.webSocketHandler.send(JSON.stringify(message));
         });
     }
+    /**
+     * Sends function responses to the server.
+     *
+     * @param functionResponses - The function responses to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    async sendFunctionResponses(functionResponses) {
+        if (this.isClosed) {
+            throw new AIError(AIErrorCode.REQUEST_ERROR, 'This LiveSession has been closed and cannot be used.');
+        }
+        const message = {
+            toolResponse: {
+                functionResponses
+            }
+        };
+        this.webSocketHandler.send(JSON.stringify(message));
+    }
     /**
      * Sends a stream of {@link GenerativeContentBlob}.
      *
@@ -3360,9 +3527,9 @@ class AudioConversationRunner {
                 }
                 else {
                     try {
-                        const resultPart = await this.options.functionCallingHandler(message.functionCalls);
+                        const functionResponse = await this.options.functionCallingHandler(message.functionCalls);
                         if (!this.isStopped) {
-                            void this.liveSession.send([resultPart]);
+                            void this.liveSession.sendFunctionResponses([functionResponse]);
                         }
                     }
                     catch (e) {
@@ -3659,17 +3826,20 @@ exports.ImagenPersonFilterLevel = ImagenPersonFilterLevel;
 exports.ImagenSafetyFilterLevel = ImagenSafetyFilterLevel;
 exports.InferenceMode = InferenceMode;
 exports.IntegerSchema = IntegerSchema;
+exports.Language = Language;
 exports.LiveGenerativeModel = LiveGenerativeModel;
 exports.LiveResponseType = LiveResponseType;
 exports.LiveSession = LiveSession;
 exports.Modality = Modality;
 exports.NumberSchema = NumberSchema;
 exports.ObjectSchema = ObjectSchema;
+exports.Outcome = Outcome;
 exports.POSSIBLE_ROLES = POSSIBLE_ROLES;
 exports.ResponseModality = ResponseModality;
 exports.Schema = Schema;
 exports.SchemaType = SchemaType;
 exports.StringSchema = StringSchema;
+exports.URLRetrievalStatus = URLRetrievalStatus;
 exports.VertexAIBackend = VertexAIBackend;
 exports.getAI = getAI;
 exports.getGenerativeModel = getGenerativeModel;