@firebase/ai 2.3.0-canary.cb3bdd812 → 2.3.0-canary.ea8512812

package/dist/ai-public.d.ts

@@ -396,7 +396,7 @@ export declare interface CitationMetadata {
 /**
  * The results of code execution run by the model.
  *
- * @public
+ * @beta
  */
 export declare interface CodeExecutionResult {
     /**
@@ -413,7 +413,7 @@ export declare interface CodeExecutionResult {
 /**
  * Represents the code execution result from the model.
  *
- * @public
+ * @beta
  */
 export declare interface CodeExecutionResultPart {
     text?: never;
@@ -430,7 +430,7 @@ export declare interface CodeExecutionResultPart {
 /**
  * A tool that enables the model to use code execution.
  *
- * @public
+ * @beta
  */
 export declare interface CodeExecutionTool {
     /**
@@ -580,7 +580,7 @@ export declare interface ErrorDetails {
 /**
  * An interface for executable code returned by the model.
  *
- * @public
+ * @beta
  */
 export declare interface ExecutableCode {
     /**
@@ -596,7 +596,7 @@ export declare interface ExecutableCode {
 /**
  * Represents the code that is executed by the model.
  *
- * @public
+ * @beta
  */
 export declare interface ExecutableCodePart {
     text?: never;
@@ -853,6 +853,7 @@ export declare interface GenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: CitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 
 /**
@@ -1862,7 +1863,7 @@ export declare class IntegerSchema extends Schema {
 /**
  * The programming language of the code.
  *
- * @public
+ * @beta
  */
 export declare const Language: {
     UNSPECIFIED: string;
@@ -1872,7 +1873,7 @@ export declare const Language: {
 /**
  * The programming language of the code.
  *
- * @public
+ * @beta
  */
 export declare type Language = (typeof Language)[keyof typeof Language];
 
@@ -2289,7 +2290,7 @@ export declare interface OnDeviceParams {
 /**
  * Represents the result of the code execution.
  *
- * @public
+ * @beta
  */
 export declare const Outcome: {
     UNSPECIFIED: string;
@@ -2301,7 +2302,7 @@ export declare const Outcome: {
 /**
  * Represents the result of the code execution.
  *
- * @public
+ * @beta
  */
 export declare type Outcome = (typeof Outcome)[keyof typeof Outcome];
 
@@ -2854,7 +2855,7 @@ export declare interface ThinkingConfig {
  * Defines a tool that model can call to access external knowledge.
  * @public
  */
-export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool;
+export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 
 /**
  * Tool config. This config is shared for all tools provided in the request.
@@ -2870,6 +2871,115 @@ export declare interface ToolConfig {
  */
 export declare type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;
 
+/**
+ * Specifies the URL Context configuration.
+ *
+ * @beta
+ */
+export declare interface URLContext {
+}
+
+/**
+ * Metadata related to {@link URLContextTool}.
+ *
+ * @beta
+ */
+export declare interface URLContextMetadata {
+    /**
+     * List of URL metadata used to provide context to the Gemini model.
+     */
+    urlMetadata: URLMetadata[];
+}
+
+/**
+ * A tool that allows you to provide additional context to the models in the form of public web
+ * URLs. By including URLs in your request, the Gemini model will access the content from those
+ * pages to inform and enhance its response.
+ *
+ * @beta
+ */
+export declare interface URLContextTool {
+    /**
+     * Specifies the URL Context configuration.
+     */
+    urlContext: URLContext;
+}
+
+/**
+ * Metadata for a single URL retrieved by the {@link URLContextTool} tool.
+ *
+ * @beta
+ */
+export declare interface URLMetadata {
+    /**
+     * The retrieved URL.
+     */
+    retrievedUrl?: string;
+    /**
+     * The status of the URL retrieval.
+     */
+    urlRetrievalStatus?: URLRetrievalStatus;
+}
+
+/**
+ * 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
+ */
+export declare const URLRetrievalStatus: {
+    /**
+     * Unspecified retrieval status.
+     */
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: string;
+    /**
+     * The URL retrieval was successful.
+     */
+    URL_RETRIEVAL_STATUS_SUCCESS: string;
+    /**
+     * The URL retrieval failed.
+     */
+    URL_RETRIEVAL_STATUS_ERROR: string;
+    /**
+     * The URL retrieval failed because the content is behind a paywall.
+     */
+    URL_RETRIEVAL_STATUS_PAYWALL: string;
+    /**
+     * The URL retrieval failed because the content is unsafe.
+     */
+    URL_RETRIEVAL_STATUS_UNSAFE: string;
+};
+
+/**
+ * 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
+ */
+export declare type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRetrievalStatus];
+
 /**
  * Usage metadata about a {@link GenerateContentResponse}.
  *
@@ -2883,8 +2993,16 @@ export declare interface UsageMetadata {
      */
     thoughtsTokenCount?: number;
     totalTokenCount: number;
+    /**
+     * The number of tokens used by tools.
+     */
+    toolUsePromptTokenCount?: number;
     promptTokensDetails?: ModalityTokenCount[];
     candidatesTokensDetails?: ModalityTokenCount[];
+    /**
+     * A list of tokens used by tools, broken down by modality.
+     */
+    toolUsePromptTokensDetails?: ModalityTokenCount[];
 }
 
 /**

package/dist/ai.d.ts

@@ -439,7 +439,7 @@ export declare interface CitationMetadata {
 /**
  * The results of code execution run by the model.
  *
- * @public
+ * @beta
  */
 export declare interface CodeExecutionResult {
     /**
@@ -456,7 +456,7 @@ export declare interface CodeExecutionResult {
 /**
  * Represents the code execution result from the model.
  *
- * @public
+ * @beta
  */
 export declare interface CodeExecutionResultPart {
     text?: never;
@@ -476,7 +476,7 @@ export declare interface CodeExecutionResultPart {
 /**
  * A tool that enables the model to use code execution.
  *
- * @public
+ * @beta
  */
 export declare interface CodeExecutionTool {
     /**
@@ -626,7 +626,7 @@ export declare interface ErrorDetails {
 /**
  * An interface for executable code returned by the model.
  *
- * @public
+ * @beta
  */
 export declare interface ExecutableCode {
     /**
@@ -642,7 +642,7 @@ export declare interface ExecutableCode {
 /**
  * Represents the code that is executed by the model.
  *
- * @public
+ * @beta
  */
 export declare interface ExecutableCodePart {
     text?: never;
@@ -911,6 +911,7 @@ export declare interface GenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: CitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 
 /**
@@ -1166,6 +1167,7 @@ export declare interface GoogleAIGenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: GoogleAICitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 
 /**
@@ -1976,7 +1978,7 @@ export declare class IntegerSchema extends Schema {
 /**
  * The programming language of the code.
  *
- * @public
+ * @beta
  */
 export declare const Language: {
     UNSPECIFIED: string;
@@ -1986,7 +1988,7 @@ export declare const Language: {
 /**
  * The programming language of the code.
  *
- * @public
+ * @beta
  */
 export declare type Language = (typeof Language)[keyof typeof Language];
 
@@ -2419,7 +2421,7 @@ export declare interface OnDeviceParams {
 /**
  * Represents the result of the code execution.
  *
- * @public
+ * @beta
  */
 export declare const Outcome: {
     UNSPECIFIED: string;
@@ -2431,7 +2433,7 @@ export declare const Outcome: {
 /**
  * Represents the result of the code execution.
  *
- * @public
+ * @beta
  */
 export declare type Outcome = (typeof Outcome)[keyof typeof Outcome];
 
@@ -2995,7 +2997,7 @@ export declare interface ThinkingConfig {
  * Defines a tool that model can call to access external knowledge.
  * @public
  */
-export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool;
+export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 
 /**
  * Tool config. This config is shared for all tools provided in the request.
@@ -3011,6 +3013,115 @@ export declare interface ToolConfig {
  */
 export declare type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;
 
+/**
+ * Specifies the URL Context configuration.
+ *
+ * @beta
+ */
+export declare interface URLContext {
+}
+
+/**
+ * Metadata related to {@link URLContextTool}.
+ *
+ * @beta
+ */
+export declare interface URLContextMetadata {
+    /**
+     * List of URL metadata used to provide context to the Gemini model.
+     */
+    urlMetadata: URLMetadata[];
+}
+
+/**
+ * A tool that allows you to provide additional context to the models in the form of public web
+ * URLs. By including URLs in your request, the Gemini model will access the content from those
+ * pages to inform and enhance its response.
+ *
+ * @beta
+ */
+export declare interface URLContextTool {
+    /**
+     * Specifies the URL Context configuration.
+     */
+    urlContext: URLContext;
+}
+
+/**
+ * Metadata for a single URL retrieved by the {@link URLContextTool} tool.
+ *
+ * @beta
+ */
+export declare interface URLMetadata {
+    /**
+     * The retrieved URL.
+     */
+    retrievedUrl?: string;
+    /**
+     * The status of the URL retrieval.
+     */
+    urlRetrievalStatus?: URLRetrievalStatus;
+}
+
+/**
+ * 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
+ */
+export declare const URLRetrievalStatus: {
+    /**
+     * Unspecified retrieval status.
+     */
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: string;
+    /**
+     * The URL retrieval was successful.
+     */
+    URL_RETRIEVAL_STATUS_SUCCESS: string;
+    /**
+     * The URL retrieval failed.
+     */
+    URL_RETRIEVAL_STATUS_ERROR: string;
+    /**
+     * The URL retrieval failed because the content is behind a paywall.
+     */
+    URL_RETRIEVAL_STATUS_PAYWALL: string;
+    /**
+     * The URL retrieval failed because the content is unsafe.
+     */
+    URL_RETRIEVAL_STATUS_UNSAFE: string;
+};
+
+/**
+ * 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
+ */
+export declare type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRetrievalStatus];
+
 /**
  * Usage metadata about a {@link GenerateContentResponse}.
  *
@@ -3024,8 +3135,16 @@ export declare interface UsageMetadata {
      */
     thoughtsTokenCount?: number;
     totalTokenCount: number;
+    /**
+     * The number of tokens used by tools.
+     */
+    toolUsePromptTokenCount?: number;
     promptTokensDetails?: ModalityTokenCount[];
     candidatesTokensDetails?: ModalityTokenCount[];
+    /**
+     * A list of tokens used by tools, broken down by modality.
+     */
+    toolUsePromptTokensDetails?: ModalityTokenCount[];
 }
 
 /**

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.3.0-canary.cb3bdd812";
+var version = "2.3.0-canary.ea8512812";
 
 /**
  * @license
@@ -382,7 +382,7 @@ const InferenceMode = {
 /**
  * Represents the result of the code execution.
  *
- * @public
+ * @beta
  */
 const Outcome = {
     UNSPECIFIED: 'OUTCOME_UNSPECIFIED',
@@ -393,7 +393,7 @@ const Outcome = {
 /**
  * The programming language of the code.
  *
- * @public
+ * @beta
  */
 const Language = {
     UNSPECIFIED: 'LANGUAGE_UNSPECIFIED',
@@ -416,6 +416,45 @@ const Language = {
  * 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}.
  *
@@ -1876,7 +1915,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 = {
@@ -1886,7 +1925,8 @@ function mapGenerateContentCandidates(candidates) {
                 finishMessage: candidate.finishMessage,
                 safetyRatings: mappedSafetyRatings,
                 citationMetadata,
-                groundingMetadata: candidate.groundingMetadata
+                groundingMetadata: candidate.groundingMetadata,
+                urlContextMetadata: candidate.urlContextMetadata
             };
             mappedCandidates.push(mappedCandidate);
         });
@@ -1977,6 +2017,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;
     }
 }
@@ -2056,36 +2104,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;
-                        }
-                        if (part.functionCall) {
-                            newPart.functionCall = part.functionCall;
+                        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 (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.');
+                        if (Object.keys(newPart).length > 0) {
+                            aggregatedResponse.candidates[i].content.parts.push(newPart);
                         }
-                        aggregatedResponse.candidates[i].content.parts.push(newPart);
                     }
                 }
             }
@@ -4035,5 +4090,5 @@ function registerAI() {
 }
 registerAI();
 
-export { AIError, AIErrorCode, AIModel, AnyOfSchema, ArraySchema, Backend, BackendType, BlockReason, BooleanSchema, ChatSession, FinishReason, FunctionCallingMode, GenerativeModel, GoogleAIBackend, HarmBlockMethod, HarmBlockThreshold, HarmCategory, HarmProbability, HarmSeverity, ImagenAspectRatio, ImagenImageFormat, ImagenModel, ImagenPersonFilterLevel, ImagenSafetyFilterLevel, InferenceMode, IntegerSchema, Language, LiveGenerativeModel, LiveResponseType, LiveSession, Modality, NumberSchema, ObjectSchema, Outcome, POSSIBLE_ROLES, ResponseModality, Schema, SchemaType, StringSchema, VertexAIBackend, getAI, getGenerativeModel, getImagenModel, getLiveGenerativeModel, startAudioConversation };
+export { AIError, AIErrorCode, AIModel, AnyOfSchema, ArraySchema, Backend, BackendType, BlockReason, BooleanSchema, ChatSession, FinishReason, FunctionCallingMode, GenerativeModel, GoogleAIBackend, HarmBlockMethod, HarmBlockThreshold, HarmCategory, HarmProbability, HarmSeverity, ImagenAspectRatio, ImagenImageFormat, ImagenModel, ImagenPersonFilterLevel, ImagenSafetyFilterLevel, InferenceMode, IntegerSchema, Language, LiveGenerativeModel, LiveResponseType, LiveSession, Modality, NumberSchema, ObjectSchema, Outcome, POSSIBLE_ROLES, ResponseModality, Schema, SchemaType, StringSchema, URLRetrievalStatus, VertexAIBackend, getAI, getGenerativeModel, getImagenModel, getLiveGenerativeModel, startAudioConversation };
 //# sourceMappingURL=index.esm.js.map