@firebase/ai 2.2.1 → 2.3.0-canary.0ffcb26af

package/dist/src/factory-browser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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.
+ */
+import { ComponentContainer, InstanceFactoryOptions } from '@firebase/component';
+import { AIService } from './service';
+export declare function factory(container: ComponentContainer, { instanceIdentifier }: InstanceFactoryOptions): AIService;

package/dist/src/requests/hybrid-helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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.
+ */
+import { GenerateContentRequest, ChromeAdapter } from '../types';
+/**
+ * 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.
+ */
+export declare function callCloudOrDevice<Response>(request: GenerateContentRequest, chromeAdapter: ChromeAdapter | undefined, onDeviceCall: () => Promise<Response>, inCloudCall: () => Promise<Response>): Promise<Response>;

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

@@ -16,13 +16,13 @@
  */
 import { CountTokensRequest, GenerateContentRequest } from './requests';
 /**
- * <b>(EXPERIMENTAL)</b> Defines an inference "backend" that uses Chrome's on-device model,
+ * Defines an inference "backend" that uses Chrome's on-device model,
  * and encapsulates logic for detecting when on-device inference is
  * possible.
  *
  * These methods should not be called directly by the user.
  *
- * @public
+ * @beta
  */
 export interface ChromeAdapter {
     /**

package/dist/src/types/content.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Role } from './enums';
+import { Language, Outcome, Role } from './enums';
 /**
  * Content type for both prompts and response candidates.
  * @public
@@ -28,7 +28,7 @@ export interface Content {
  * part types.
  * @public
  */
-export type Part = TextPart | InlineDataPart | FunctionCallPart | FunctionResponsePart | FileDataPart;
+export type Part = TextPart | InlineDataPart | FunctionCallPart | FunctionResponsePart | FileDataPart | ExecutableCodePart | CodeExecutionResultPart;
 /**
  * Content part interface if the part represents a text string.
  * @public
@@ -43,6 +43,8 @@ export interface TextPart {
      * @internal
      */
     thoughtSignature?: string;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 /**
  * Content part interface if the part represents an image.
@@ -62,6 +64,8 @@ export interface InlineDataPart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 /**
  * Describes the input video content.
@@ -93,6 +97,8 @@ export interface FunctionCallPart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 /**
  * Content part interface if the part represents {@link FunctionResponse}.
@@ -108,6 +114,8 @@ export interface FunctionResponsePart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 /**
  * Content part interface if the part represents {@link FileData}
@@ -124,6 +132,77 @@ export interface FileDataPart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
+}
+/**
+ * Represents the code that is executed by the model.
+ *
+ * @public
+ */
+export interface ExecutableCodePart {
+    text?: never;
+    inlineData?: never;
+    functionCall?: never;
+    functionResponse?: never;
+    fileData: never;
+    thought?: never;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
+    executableCode?: ExecutableCode;
+    codeExecutionResult?: never;
+}
+/**
+ * Represents the code execution result from the model.
+ *
+ * @public
+ */
+export interface CodeExecutionResultPart {
+    text?: never;
+    inlineData?: never;
+    functionCall?: never;
+    functionResponse?: never;
+    fileData: never;
+    thought?: never;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: CodeExecutionResult;
+}
+/**
+ * An interface for executable code returned by the model.
+ *
+ * @public
+ */
+export interface ExecutableCode {
+    /**
+     * The programming language of the code.
+     */
+    language?: Language;
+    /**
+     * The source code to be executed.
+     */
+    code?: string;
+}
+/**
+ * The results of code execution run by the model.
+ *
+ * @public
+ */
+export interface CodeExecutionResult {
+    /**
+     * The result of the code execution.
+     */
+    outcome?: Outcome;
+    /**
+     * The output from the code execution, or an error message
+     * if it failed.
+     */
+    output?: string;
 }
 /**
  * A predicted {@link FunctionCall} returned from the model

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

@@ -317,18 +317,67 @@ export declare const ResponseModality: {
  */
 export type ResponseModality = (typeof ResponseModality)[keyof typeof ResponseModality];
 /**
- * <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
  */
 export declare const InferenceMode: {
     readonly PREFER_ON_DEVICE: "prefer_on_device";
     readonly ONLY_ON_DEVICE: "only_on_device";
     readonly ONLY_IN_CLOUD: "only_in_cloud";
+    readonly PREFER_IN_CLOUD: "prefer_in_cloud";
 };
 /**
- * <b>(EXPERIMENTAL)</b>
  * Determines whether inference happens on-device or in-cloud.
- * @public
+ *
+ * @beta
  */
 export type InferenceMode = (typeof InferenceMode)[keyof typeof InferenceMode];
+/**
+ * Represents the result of the code execution.
+ *
+ * @public
+ */
+export declare const Outcome: {
+    UNSPECIFIED: string;
+    OK: string;
+    FAILED: string;
+    DEADLINE_EXCEEDED: string;
+};
+/**
+ * Represents the result of the code execution.
+ *
+ * @public
+ */
+export type Outcome = (typeof Outcome)[keyof typeof Outcome];
+/**
+ * The programming language of the code.
+ *
+ * @public
+ */
+export declare const Language: {
+    UNSPECIFIED: string;
+    PYTHON: string;
+};
+/**
+ * The programming language of the code.
+ *
+ * @public
+ */
+export type Language = (typeof Language)[keyof typeof Language];

package/dist/src/types/googleai.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Tool, GenerationConfig, Citation, FinishReason, GroundingMetadata, PromptFeedback, SafetyRating, UsageMetadata } from '../public-types';
+import { Tool, GenerationConfig, Citation, FinishReason, GroundingMetadata, PromptFeedback, SafetyRating, UsageMetadata, URLContextMetadata } from '../public-types';
 import { Content, Part } from './content';
 /**
  * @internal
@@ -47,6 +47,7 @@ export interface GoogleAIGenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: GoogleAICitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 /**
  * @internal

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

@@ -39,9 +39,8 @@ export declare enum Availability {
     'AVAILABLE' = "available"
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * Configures the creation of an on-device language model session.
- * @public
+ * @beta
  */
 export interface LanguageModelCreateCoreOptions {
     topK?: number;
@@ -49,69 +48,60 @@ export interface LanguageModelCreateCoreOptions {
     expectedInputs?: LanguageModelExpected[];
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * Configures the creation of an on-device language model session.
- * @public
+ * @beta
  */
 export interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
     signal?: AbortSignal;
     initialPrompts?: LanguageModelMessage[];
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * Options for an on-device language model prompt.
- * @public
+ * @beta
  */
 export interface LanguageModelPromptOptions {
     responseConstraint?: object;
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * Options for the expected inputs for an on-device language model.
- * @public
+ * @beta
  */ export interface LanguageModelExpected {
     type: LanguageModelMessageType;
     languages?: string[];
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * An on-device language model prompt.
- * @public
+ * @beta
  */
 export type LanguageModelPrompt = LanguageModelMessage[];
 /**
- * <b>(EXPERIMENTAL)</b>
  * An on-device language model message.
- * @public
+ * @beta
  */
 export interface LanguageModelMessage {
     role: LanguageModelMessageRole;
     content: LanguageModelMessageContent[];
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * An on-device language model content object.
- * @public
+ * @beta
  */
 export interface LanguageModelMessageContent {
     type: LanguageModelMessageType;
     value: LanguageModelMessageContentValue;
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * Allowable roles for on-device language model usage.
- * @public
+ * @beta
  */
 export type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
 /**
- * <b>(EXPERIMENTAL)</b>
  * Allowable types for on-device language model messages.
- * @public
+ * @beta
  */
 export type LanguageModelMessageType = 'text' | 'image' | 'audio';
 /**
- * <b>(EXPERIMENTAL)</b>
  * Content formats that can be provided as on-device message content.
- * @public
+ * @beta
  */
 export type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;

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

@@ -218,7 +218,7 @@ export interface RequestOptions {
  * Defines a tool that model can call to access external knowledge.
  * @public
  */
-export type Tool = FunctionDeclarationsTool | GoogleSearchTool;
+export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 /**
  * Structured representation of a function declaration as defined by the
  * {@link https://spec.openapis.org/oas/v3.0.3 | OpenAPI 3.0 specification}.
@@ -262,8 +262,6 @@ export interface GoogleSearchTool {
     /**
      * Specifies the Google Search configuration.
      * Currently, this is an empty object, but it's reserved for future configuration options.
-     * Specifies the Google Search configuration. Currently, this is an empty object, but it's
-     * reserved for future configuration options.
      *
      * When using this feature, you are required to comply with the "Grounding with Google Search"
      * usage requirements for your chosen API provider: {@link https://ai.google.dev/gemini-api/terms#grounding-with-google-search | Gemini Developer API}
@@ -272,6 +270,18 @@ export interface GoogleSearchTool {
      */
     googleSearch: GoogleSearch;
 }
+/**
+ * A tool that enables the model to use code execution.
+ *
+ * @public
+ */
+export interface CodeExecutionTool {
+    /**
+     * Specifies the Google Search configuration.
+     * Currently, this is an empty object, but it's reserved for future configuration options.
+     */
+    codeExecution: {};
+}
 /**
  * Specifies the Google Search configuration.
  *
@@ -281,6 +291,26 @@ export interface GoogleSearchTool {
  */
 export interface GoogleSearch {
 }
+/**
+ * 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 interface URLContextTool {
+    /**
+     * Specifies the URL Context configuration.
+     */
+    urlContext: URLContext;
+}
+/**
+ * Specifies the URL Context configuration.
+ *
+ * @beta
+ */
+export interface URLContext {
+}
 /**
  * A `FunctionDeclarationsTool` is a piece of code that enables the system to
  * interact with external systems to perform an action, or set of actions,
@@ -315,19 +345,17 @@ export interface FunctionCallingConfig {
     allowedFunctionNames?: string[];
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * Encapsulates configuration for on-device inference.
  *
- * @public
+ * @beta
  */
 export interface OnDeviceParams {
     createOptions?: LanguageModelCreateOptions;
     promptOptions?: LanguageModelPromptOptions;
 }
 /**
- * <b>(EXPERIMENTAL)</b>
  * Configures hybrid inference.
- * @public
+ * @beta
  */
 export interface HybridParams {
     /**

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

@@ -102,8 +102,16 @@ export 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[];
 }
 /**
  * Represents token counting info for a single modality.
@@ -143,6 +151,7 @@ export interface GenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: CitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 /**
  * Citation metadata that may be found on a {@link GenerateContentCandidate}.
@@ -323,6 +332,89 @@ export interface Segment {
      */
     text: string;
 }
+/**
+ * Metadata related to {@link URLContextTool}.
+ *
+ * @beta
+ */
+export interface URLContextMetadata {
+    /**
+     * List of URL metadata used to provide context to the Gemini model.
+     */
+    urlMetadata: URLMetadata[];
+}
+/**
+ * Metadata for a single URL retrieved by the {@link URLContextTool} tool.
+ *
+ * @beta
+ */
+export 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 type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRetrievalStatus];
 /**
  * @public
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebase/ai",
-  "version": "2.2.1",
+  "version": "2.3.0-canary.0ffcb26af",
   "description": "The Firebase AI SDK",
   "author": "Firebase <firebase-support@google.com> (https://firebase.google.com/)",
   "engines": {
@@ -35,7 +35,7 @@
     "dev": "rollup -c -w",
     "update-responses": "../../scripts/update_vertexai_responses.sh",
     "testsetup": "yarn update-responses && yarn ts-node ./test-utils/convert-mocks.ts",
-    "test": "run-p --npm-path npm lint test:browser",
+    "test": "run-p --npm-path npm lint type-check test:browser",
     "test:ci": "yarn testsetup && node ../../scripts/run_tests_in_ci.js -s test",
     "test:skip-clone": "karma start",
     "test:browser": "yarn testsetup && karma start",
@@ -44,22 +44,23 @@
     "test:integration:node": "TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' mocha integration/**/*.test.ts --config ../../config/mocharc.node.js",
     "api-report": "api-extractor run --local --verbose",
     "typings:public": "node ../../scripts/build/use_typings.js ./dist/ai-public.d.ts",
+    "type-check": "yarn tsc --noEmit",
     "trusted-type-check": "tsec -p tsconfig.json --noEmit"
   },
   "peerDependencies": {
-    "@firebase/app": "0.x",
-    "@firebase/app-types": "0.x"
+    "@firebase/app": "0.14.3-canary.0ffcb26af",
+    "@firebase/app-types": "0.9.3-canary.0ffcb26af"
   },
   "dependencies": {
-    "@firebase/app-check-interop-types": "0.3.3",
-    "@firebase/component": "0.7.0",
-    "@firebase/logger": "0.5.0",
-    "@firebase/util": "1.13.0",
+    "@firebase/app-check-interop-types": "0.3.3-canary.0ffcb26af",
+    "@firebase/component": "0.7.0-canary.0ffcb26af",
+    "@firebase/logger": "0.5.0-canary.0ffcb26af",
+    "@firebase/util": "1.13.0-canary.0ffcb26af",
     "tslib": "^2.1.0"
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "@firebase/app": "0.14.2",
+    "@firebase/app": "0.14.3-canary.0ffcb26af",
     "@rollup/plugin-json": "6.1.0",
     "rollup": "2.79.2",
     "rollup-plugin-replace": "2.2.0",