@firebase/ai 2.0.0 → 2.1.0

package/dist/src/api.d.ts

@@ -18,7 +18,7 @@ import { FirebaseApp } from '@firebase/app';
 import { AI_TYPE } from './constants';
 import { AIService } from './service';
 import { AI, AIOptions } from './public-types';
-import { ImagenModelParams, ModelParams, RequestOptions } from './types';
+import { ImagenModelParams, HybridParams, ModelParams, RequestOptions } from './types';
 import { AIError } from './errors';
 import { AIModel, GenerativeModel, ImagenModel } from './models';
 export { ChatSession } from './methods/chat-session';
@@ -66,7 +66,7 @@ export declare function getAI(app?: FirebaseApp, options?: AIOptions): AI;
  *
  * @public
  */
-export declare function getGenerativeModel(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions): GenerativeModel;
+export declare function getGenerativeModel(ai: AI, modelParams: ModelParams | HybridParams, requestOptions?: RequestOptions): GenerativeModel;
 /**
  * Returns an {@link ImagenModel} class with methods for using Imagen.
  *

package/dist/src/constants.d.ts

@@ -21,3 +21,7 @@ export declare const DEFAULT_API_VERSION = "v1beta";
 export declare const PACKAGE_VERSION: string;
 export declare const LANGUAGE_TAG = "gl-js";
 export declare const DEFAULT_FETCH_TIMEOUT_MS: number;
+/**
+ * Defines the name of the default in-cloud model to use for hybrid inference.
+ */
+export declare const DEFAULT_HYBRID_IN_CLOUD_MODEL = "gemini-2.0-flash-lite";

package/dist/src/methods/chat-session.d.ts

@@ -16,6 +16,7 @@
  */
 import { Content, GenerateContentResult, GenerateContentStreamResult, Part, RequestOptions, StartChatParams } from '../types';
 import { ApiSettings } from '../types/internal';
+import { ChromeAdapter } from '../types/chrome-adapter';
 /**
  * ChatSession class that enables sending chat messages and stores
  * history of sent and received messages so far.
@@ -24,12 +25,13 @@ import { ApiSettings } from '../types/internal';
  */
 export declare class ChatSession {
     model: string;
+    private chromeAdapter?;
     params?: StartChatParams | undefined;
     requestOptions?: RequestOptions | undefined;
     private _apiSettings;
     private _history;
     private _sendPromise;
-    constructor(apiSettings: ApiSettings, model: string, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
+    constructor(apiSettings: ApiSettings, model: string, chromeAdapter?: ChromeAdapter | undefined, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
     /**
      * Gets the chat history so far. Blocked prompts are not added to history.
      * Neither blocked candidates nor the prompts that generated them are added

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

@@ -0,0 +1,118 @@
+/**
+ * @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 { CountTokensRequest, GenerateContentRequest, InferenceMode, OnDeviceParams } from '../types';
+import { ChromeAdapter } from '../types/chrome-adapter';
+import { LanguageModel } from '../types/language-model';
+/**
+ * Defines an inference "backend" that uses Chrome's on-device model,
+ * and encapsulates logic for detecting when on-device inference is
+ * possible.
+ */
+export declare class ChromeAdapterImpl implements ChromeAdapter {
+    private languageModelProvider;
+    private mode;
+    private onDeviceParams;
+    static SUPPORTED_MIME_TYPES: string[];
+    private isDownloading;
+    private downloadPromise;
+    private oldSession;
+    constructor(languageModelProvider: LanguageModel, mode: InferenceMode, onDeviceParams?: OnDeviceParams);
+    /**
+     * 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>
+     */
+    isAvailable(request: GenerateContentRequest): Promise<boolean>;
+    /**
+     * 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.
+     */
+    generateContent(request: GenerateContentRequest): Promise<Response>;
+    /**
+     * 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.
+     */
+    generateContentStream(request: GenerateContentRequest): Promise<Response>;
+    countTokens(_request: CountTokensRequest): Promise<Response>;
+    /**
+     * Asserts inference for the given request can be performed by an on-device model.
+     */
+    private static isOnDeviceRequest;
+    /**
+     * Encapsulates logic to get availability and download a model if one is downloadable.
+     */
+    private downloadIfAvailable;
+    /**
+     * 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>
+     */
+    private download;
+    /**
+     * Converts Firebase AI {@link Content} object to a Chrome {@link LanguageModelMessage} object.
+     */
+    private static toLanguageModelMessage;
+    /**
+     * Converts a Firebase AI Part object to a Chrome LanguageModelMessageContent object.
+     */
+    private static toLanguageModelMessageContent;
+    /**
+     * Converts a Firebase AI {@link Role} string to a {@link LanguageModelMessageRole} string.
+     */
+    private static toLanguageModelMessageRole;
+    /**
+     * 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>
+     */
+    private createSession;
+    /**
+     * Formats string returned by Chrome as a {@link Response} returned by Firebase AI.
+     */
+    private static toResponse;
+    /**
+     * Formats string stream returned by Chrome as SSE returned by Firebase AI.
+     */
+    private static toStreamResponse;
+}

package/dist/src/methods/count-tokens.d.ts

@@ -16,4 +16,6 @@
  */
 import { CountTokensRequest, CountTokensResponse, RequestOptions } from '../types';
 import { ApiSettings } from '../types/internal';
-export declare function countTokens(apiSettings: ApiSettings, model: string, params: CountTokensRequest, requestOptions?: RequestOptions): Promise<CountTokensResponse>;
+import { ChromeAdapter } from '../types/chrome-adapter';
+export declare function countTokensOnCloud(apiSettings: ApiSettings, model: string, params: CountTokensRequest, requestOptions?: RequestOptions): Promise<CountTokensResponse>;
+export declare function countTokens(apiSettings: ApiSettings, model: string, params: CountTokensRequest, chromeAdapter?: ChromeAdapter, requestOptions?: RequestOptions): Promise<CountTokensResponse>;

package/dist/src/methods/generate-content.d.ts

@@ -16,5 +16,6 @@
  */
 import { GenerateContentRequest, GenerateContentResult, GenerateContentStreamResult, RequestOptions } from '../types';
 import { ApiSettings } from '../types/internal';
-export declare function generateContentStream(apiSettings: ApiSettings, model: string, params: GenerateContentRequest, requestOptions?: RequestOptions): Promise<GenerateContentStreamResult>;
-export declare function generateContent(apiSettings: ApiSettings, model: string, params: GenerateContentRequest, requestOptions?: RequestOptions): Promise<GenerateContentResult>;
+import { ChromeAdapter } from '../types/chrome-adapter';
+export declare function generateContentStream(apiSettings: ApiSettings, model: string, params: GenerateContentRequest, chromeAdapter?: ChromeAdapter, requestOptions?: RequestOptions): Promise<GenerateContentStreamResult>;
+export declare function generateContent(apiSettings: ApiSettings, model: string, params: GenerateContentRequest, chromeAdapter?: ChromeAdapter, requestOptions?: RequestOptions): Promise<GenerateContentResult>;

package/dist/src/models/generative-model.d.ts

@@ -18,18 +18,20 @@ import { Content, CountTokensRequest, CountTokensResponse, GenerateContentReques
 import { ChatSession } from '../methods/chat-session';
 import { AI } from '../public-types';
 import { AIModel } from './ai-model';
+import { ChromeAdapter } from '../types/chrome-adapter';
 /**
  * Class for generative model APIs.
  * @public
  */
 export declare class GenerativeModel extends AIModel {
+    private chromeAdapter?;
     generationConfig: GenerationConfig;
     safetySettings: SafetySetting[];
     requestOptions?: RequestOptions;
     tools?: Tool[];
     toolConfig?: ToolConfig;
     systemInstruction?: Content;
-    constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions);
+    constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions, chromeAdapter?: ChromeAdapter | undefined);
     /**
      * Makes a single non-streaming call to the model
      * and returns an object containing a single {@link GenerateContentResponse}.

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

@@ -0,0 +1,54 @@
+/**
+ * @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 { CountTokensRequest, GenerateContentRequest } from './requests';
+/**
+ * <b>(EXPERIMENTAL)</b> 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
+ */
+export interface ChromeAdapter {
+    /**
+     * Checks if the on-device model is capable of handling a given
+     * request.
+     * @param request - A potential request to be passed to the model.
+     */
+    isAvailable(request: GenerateContentRequest): Promise<boolean>;
+    /**
+     * Generates content using on-device inference.
+     *
+     * <p>This is comparable to {@link GenerativeModel.generateContent} for generating
+     * content using in-cloud inference.</p>
+     * @param request - a standard Firebase AI {@link GenerateContentRequest}
+     */
+    generateContent(request: GenerateContentRequest): Promise<Response>;
+    /**
+     * Generates a content stream using on-device inference.
+     *
+     * <p>This is comparable to {@link GenerativeModel.generateContentStream} for generating
+     * a content stream using in-cloud inference.</p>
+     * @param request - a standard Firebase AI {@link GenerateContentRequest}
+     */
+    generateContentStream(request: GenerateContentRequest): Promise<Response>;
+    /**
+     * @internal
+     */
+    countTokens(request: CountTokensRequest): Promise<Response>;
+}

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

@@ -62,7 +62,7 @@ export declare const HarmBlockThreshold: {
     readonly 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.
      */
     readonly OFF: "OFF";
 };
@@ -249,6 +249,9 @@ export declare const FunctionCallingMode: {
      */
     readonly NONE: "NONE";
 };
+/**
+ * @public
+ */
 export type FunctionCallingMode = (typeof FunctionCallingMode)[keyof typeof FunctionCallingMode];
 /**
  * Content part modality.
@@ -308,3 +311,19 @@ export declare const ResponseModality: {
  * @beta
  */
 export type ResponseModality = (typeof ResponseModality)[keyof typeof ResponseModality];
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Determines whether inference happens on-device or in-cloud.
+ * @public
+ */
+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";
+};
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Determines whether inference happens on-device or in-cloud.
+ * @public
+ */
+export type InferenceMode = (typeof InferenceMode)[keyof typeof InferenceMode];

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

@@ -204,7 +204,7 @@ export interface ImagenSafetySettings {
  * 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
@@ -237,7 +237,7 @@ export declare const ImagenAspectRatio: {
  * 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

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

@@ -35,6 +35,7 @@ export interface ImagenInlineImage {
  * An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.
  *
  * This feature is not available yet.
+ * @beta
  */
 export interface ImagenGCSImage {
     /**

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

@@ -22,3 +22,5 @@ export * from './error';
 export * from './schema';
 export * from './imagen';
 export * from './googleai';
+export { LanguageModelCreateOptions, LanguageModelCreateCoreOptions, LanguageModelExpected, LanguageModelMessage, LanguageModelMessageContent, LanguageModelMessageContentValue, LanguageModelMessageRole, LanguageModelMessageType, LanguageModelPromptOptions } from './language-model';
+export * from './chrome-adapter';

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

@@ -0,0 +1,117 @@
+/**
+ * @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.
+ */
+/**
+ * The subset of the Prompt API
+ * (see {@link https://github.com/webmachinelearning/prompt-api#full-api-surface-in-web-idl }
+ * required for hybrid functionality.
+ *
+ * @internal
+ */
+export interface LanguageModel extends EventTarget {
+    create(options?: LanguageModelCreateOptions): Promise<LanguageModel>;
+    availability(options?: LanguageModelCreateCoreOptions): Promise<Availability>;
+    prompt(input: LanguageModelPrompt, options?: LanguageModelPromptOptions): Promise<string>;
+    promptStreaming(input: LanguageModelPrompt, options?: LanguageModelPromptOptions): ReadableStream;
+    measureInputUsage(input: LanguageModelPrompt, options?: LanguageModelPromptOptions): Promise<number>;
+    destroy(): undefined;
+}
+/**
+ * @internal
+ */
+export declare enum Availability {
+    'UNAVAILABLE' = "unavailable",
+    'DOWNLOADABLE' = "downloadable",
+    'DOWNLOADING' = "downloading",
+    'AVAILABLE' = "available"
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Configures the creation of an on-device language model session.
+ * @public
+ */
+export interface LanguageModelCreateCoreOptions {
+    topK?: number;
+    temperature?: number;
+    expectedInputs?: LanguageModelExpected[];
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Configures the creation of an on-device language model session.
+ * @public
+ */
+export interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
+    signal?: AbortSignal;
+    initialPrompts?: LanguageModelMessage[];
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Options for an on-device language model prompt.
+ * @public
+ */
+export interface LanguageModelPromptOptions {
+    responseConstraint?: object;
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Options for the expected inputs for an on-device language model.
+ * @public
+ */ export interface LanguageModelExpected {
+    type: LanguageModelMessageType;
+    languages?: string[];
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * An on-device language model prompt.
+ * @public
+ */
+export type LanguageModelPrompt = LanguageModelMessage[];
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * An on-device language model message.
+ * @public
+ */
+export interface LanguageModelMessage {
+    role: LanguageModelMessageRole;
+    content: LanguageModelMessageContent[];
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * An on-device language model content object.
+ * @public
+ */
+export interface LanguageModelMessageContent {
+    type: LanguageModelMessageType;
+    value: LanguageModelMessageContentValue;
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Allowable roles for on-device language model usage.
+ * @public
+ */
+export type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Allowable types for on-device language model messages.
+ * @public
+ */
+export type LanguageModelMessageType = 'text' | 'image' | 'audio';
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Content formats that can be provided as on-device message content.
+ * @public
+ */
+export type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;

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

@@ -16,7 +16,8 @@
  */
 import { ObjectSchema, TypedSchema } from '../requests/schema-builder';
 import { Content, Part } from './content';
-import { FunctionCallingMode, HarmBlockMethod, HarmBlockThreshold, HarmCategory, ResponseModality } from './enums';
+import { LanguageModelCreateOptions, LanguageModelPromptOptions } from './language-model';
+import { FunctionCallingMode, HarmBlockMethod, HarmBlockThreshold, HarmCategory, InferenceMode, ResponseModality } from './enums';
 import { ObjectSchemaRequest, SchemaRequest } from './schema';
 /**
  * Base parameters for a number of methods.
@@ -249,6 +250,35 @@ export interface FunctionCallingConfig {
     mode?: FunctionCallingMode;
     allowedFunctionNames?: string[];
 }
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Encapsulates configuration for on-device inference.
+ *
+ * @public
+ */
+export interface OnDeviceParams {
+    createOptions?: LanguageModelCreateOptions;
+    promptOptions?: LanguageModelPromptOptions;
+}
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Configures hybrid inference.
+ * @public
+ */
+export interface HybridParams {
+    /**
+     * Specifies on-device or in-cloud inference. Defaults to prefer on-device.
+     */
+    mode: InferenceMode;
+    /**
+     * Optional. Specifies advanced params for on-device inference.
+     */
+    onDeviceParams?: OnDeviceParams;
+    /**
+     * Optional. Specifies advanced params for in-cloud inference.
+     */
+    inCloudParams?: ModelParams;
+}
 /**
  * Configuration for "thinking" behavior of compatible Gemini models.
  *

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

@@ -170,7 +170,7 @@ export interface GroundingMetadata {
     /**
      * Google Search entry point for web searches. This contains an HTML/CSS snippet that must be
      * embedded in an app to display a Google Search entry point for follow-up web searches related to
-     * a model's “Grounded Response”.
+     * a model's "Grounded Response".
      */
     searchEntryPoint?: SearchEntrypoint;
     /**

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

@@ -122,7 +122,7 @@ export interface SchemaInterface extends SchemaShared<SchemaInterface> {
     type?: SchemaType;
 }
 /**
- * Interface for JSON parameters in a schema of {@link SchemaType}
+ * Interface for JSON parameters in a schema of {@link (SchemaType:type)}
  * "object" when not using the `Schema.object()` helper.
  * @public
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebase/ai",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "The Firebase AI SDK",
   "author": "Firebase <firebase-support@google.com> (https://firebase.google.com/)",
   "engines": {
@@ -57,7 +57,7 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "@firebase/app": "0.14.0",
+    "@firebase/app": "0.14.1",
     "@rollup/plugin-json": "6.1.0",
     "rollup": "2.79.2",
     "rollup-plugin-replace": "2.2.0",