@firebase/ai 1.2.2-canary.f92069a21 → 1.2.2-eap-ai-hybridinference.58d92df33

package/dist/ai-public.d.ts

@@ -150,6 +150,13 @@ export declare class ArraySchema extends Schema {
     /* Excluded from this release type: toJSON */
 }
 
+declare enum Availability {
+    'unavailable' = "unavailable",
+    'downloadable' = "downloadable",
+    'downloading' = "downloading",
+    'available' = "available"
+}
+
 /**
  * Abstract base class representing the configuration for an AI service backend.
  * This class should not be instantiated directly. Use its subclasses; {@link GoogleAIBackend} for
@@ -251,12 +258,13 @@ export declare class BooleanSchema extends Schema {
  */
 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, 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
@@ -276,6 +284,105 @@ export declare class ChatSession {
     sendMessageStream(request: string | Array<string | Part>): Promise<GenerateContentStreamResult>;
 }
 
+/**
+ * Defines an inference "backend" that uses Chrome's on-device model,
+ * and encapsulates logic for detecting when on-device is possible.
+ */
+declare class ChromeAdapter {
+    private languageModelProvider?;
+    private mode?;
+    private onDeviceParams;
+    static SUPPORTED_MIME_TYPES: string[];
+    private isDownloading;
+    private downloadPromise;
+    private oldSession;
+    constructor(languageModelProvider?: LanguageModel | undefined, mode?: InferenceMode | undefined, 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 Vertex {@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 Vertex {@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 Vertex {@link Content} object to a Chrome {@link LanguageModelMessage} object.
+     */
+    private static toLanguageModelMessage;
+    /**
+     * Converts a Vertex Part object to a Chrome LanguageModelMessageContent object.
+     */
+    private static toLanguageModelMessageContent;
+    /**
+     * Converts a Vertex {@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. Vertex uses single-turn for all
+     * inference. To map the Vertex 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 Vertex.
+     */
+    private static toResponse;
+    /**
+     * Formats string stream returned by Chrome as SSE returned by Vertex.
+     */
+    private static toStreamResponse;
+}
+
 /**
  * A single citation.
  * @public
@@ -735,13 +842,18 @@ export declare interface GenerativeContentBlob {
  * @public
  */
 export declare class GenerativeModel extends AIModel {
+    private chromeAdapter;
+    /**
+     * Defines the name of the default in-cloud model to use for hybrid inference.
+     */
+    static DEFAULT_HYBRID_IN_CLOUD_MODEL: string;
     generationConfig: GenerationConfig;
     safetySettings: SafetySetting[];
     requestOptions?: RequestOptions;
     tools?: Tool[];
     toolConfig?: ToolConfig;
     systemInstruction?: Content;
-    constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions);
+    constructor(ai: AI, modelParams: ModelParams, chromeAdapter: ChromeAdapter, requestOptions?: RequestOptions);
     /**
      * Makes a single non-streaming call to the model
      * and returns an object containing a single {@link GenerateContentResponse}.
@@ -801,7 +913,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.
@@ -985,6 +1097,24 @@ export declare enum HarmSeverity {
     HARM_SEVERITY_UNSUPPORTED = "HARM_SEVERITY_UNSUPPORTED"
 }
 
+/**
+ * Toggles hybrid inference.
+ */
+export declare 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;
+}
+
 /**
  * Aspect ratios for Imagen images.
  *
@@ -1393,6 +1523,11 @@ export declare interface ImagenSafetySettings {
     personFilterLevel?: ImagenPersonFilterLevel;
 }
 
+/**
+ * Determines whether inference happens on-device or in-cloud.
+ */
+export declare type InferenceMode = 'prefer_on_device' | 'only_on_device' | 'only_in_cloud';
+
 /**
  * Content part interface if the part represents an image.
  * @public
@@ -1416,6 +1551,74 @@ export declare class IntegerSchema extends Schema {
     constructor(schemaParams?: SchemaParams);
 }
 
+/**
+ * @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 https://github.com/webmachinelearning/prompt-api#full-api-surface-in-web-idl})
+ * required for hybrid functionality.
+ */
+declare 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;
+}
+
+export declare interface LanguageModelCreateCoreOptions {
+    topK?: number;
+    temperature?: number;
+    expectedInputs?: LanguageModelExpected[];
+}
+
+export declare interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
+    signal?: AbortSignal;
+    initialPrompts?: LanguageModelMessage[];
+}
+
+export declare interface LanguageModelExpected {
+    type: LanguageModelMessageType;
+    languages?: string[];
+}
+
+export declare interface LanguageModelMessage {
+    role: LanguageModelMessageRole;
+    content: LanguageModelMessageContent[];
+}
+
+export declare interface LanguageModelMessageContent {
+    type: LanguageModelMessageType;
+    value: LanguageModelMessageContentValue;
+}
+
+export declare type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;
+
+export declare type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
+
+export declare type LanguageModelMessageType = 'text' | 'image' | 'audio';
+
+declare type LanguageModelPrompt = LanguageModelMessage[];
+
+declare interface LanguageModelPromptOptions {
+    responseConstraint?: object;
+}
+
 /**
  * Content part modality.
  * @public
@@ -1503,6 +1706,14 @@ export declare interface ObjectSchemaInterface extends SchemaInterface {
     optionalProperties?: string[];
 }
 
+/**
+ * Encapsulates configuration for on-device inference.
+ */
+export declare interface OnDeviceParams {
+    createOptions?: LanguageModelCreateOptions;
+    promptOptions?: LanguageModelPromptOptions;
+}
+
 /**
  * Content part - includes text, image/video, or function call/response
  * part types.

package/dist/ai.d.ts

@@ -187,6 +187,13 @@ export declare class ArraySchema extends Schema {
     toJSON(): SchemaRequest;
 }
 
+declare enum Availability {
+    'unavailable' = "unavailable",
+    'downloadable' = "downloadable",
+    'downloading' = "downloading",
+    'available' = "available"
+}
+
 /**
  * Abstract base class representing the configuration for an AI service backend.
  * This class should not be instantiated directly. Use its subclasses; {@link GoogleAIBackend} for
@@ -288,12 +295,13 @@ export declare class BooleanSchema extends Schema {
  */
 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, 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
@@ -313,6 +321,105 @@ export declare class ChatSession {
     sendMessageStream(request: string | Array<string | Part>): Promise<GenerateContentStreamResult>;
 }
 
+/**
+ * Defines an inference "backend" that uses Chrome's on-device model,
+ * and encapsulates logic for detecting when on-device is possible.
+ */
+declare class ChromeAdapter {
+    private languageModelProvider?;
+    private mode?;
+    private onDeviceParams;
+    static SUPPORTED_MIME_TYPES: string[];
+    private isDownloading;
+    private downloadPromise;
+    private oldSession;
+    constructor(languageModelProvider?: LanguageModel | undefined, mode?: InferenceMode | undefined, 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 Vertex {@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 Vertex {@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 Vertex {@link Content} object to a Chrome {@link LanguageModelMessage} object.
+     */
+    private static toLanguageModelMessage;
+    /**
+     * Converts a Vertex Part object to a Chrome LanguageModelMessageContent object.
+     */
+    private static toLanguageModelMessageContent;
+    /**
+     * Converts a Vertex {@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. Vertex uses single-turn for all
+     * inference. To map the Vertex 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 Vertex.
+     */
+    private static toResponse;
+    /**
+     * Formats string stream returned by Chrome as SSE returned by Vertex.
+     */
+    private static toStreamResponse;
+}
+
 /**
  * A single citation.
  * @public
@@ -772,13 +879,18 @@ export declare interface GenerativeContentBlob {
  * @public
  */
 export declare class GenerativeModel extends AIModel {
+    private chromeAdapter;
+    /**
+     * Defines the name of the default in-cloud model to use for hybrid inference.
+     */
+    static DEFAULT_HYBRID_IN_CLOUD_MODEL: string;
     generationConfig: GenerationConfig;
     safetySettings: SafetySetting[];
     requestOptions?: RequestOptions;
     tools?: Tool[];
     toolConfig?: ToolConfig;
     systemInstruction?: Content;
-    constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions);
+    constructor(ai: AI, modelParams: ModelParams, chromeAdapter: ChromeAdapter, requestOptions?: RequestOptions);
     /**
      * Makes a single non-streaming call to the model
      * and returns an object containing a single {@link GenerateContentResponse}.
@@ -838,7 +950,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.
@@ -1056,6 +1168,24 @@ export declare enum HarmSeverity {
     HARM_SEVERITY_UNSUPPORTED = "HARM_SEVERITY_UNSUPPORTED"
 }
 
+/**
+ * Toggles hybrid inference.
+ */
+export declare 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;
+}
+
 /**
  * Aspect ratios for Imagen images.
  *
@@ -1483,6 +1613,11 @@ export declare interface ImagenSafetySettings {
     personFilterLevel?: ImagenPersonFilterLevel;
 }
 
+/**
+ * Determines whether inference happens on-device or in-cloud.
+ */
+export declare type InferenceMode = 'prefer_on_device' | 'only_on_device' | 'only_in_cloud';
+
 /**
  * Content part interface if the part represents an image.
  * @public
@@ -1506,6 +1641,74 @@ export declare class IntegerSchema extends Schema {
     constructor(schemaParams?: SchemaParams);
 }
 
+/**
+ * @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 https://github.com/webmachinelearning/prompt-api#full-api-surface-in-web-idl})
+ * required for hybrid functionality.
+ */
+declare 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;
+}
+
+export declare interface LanguageModelCreateCoreOptions {
+    topK?: number;
+    temperature?: number;
+    expectedInputs?: LanguageModelExpected[];
+}
+
+export declare interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
+    signal?: AbortSignal;
+    initialPrompts?: LanguageModelMessage[];
+}
+
+export declare interface LanguageModelExpected {
+    type: LanguageModelMessageType;
+    languages?: string[];
+}
+
+export declare interface LanguageModelMessage {
+    role: LanguageModelMessageRole;
+    content: LanguageModelMessageContent[];
+}
+
+export declare interface LanguageModelMessageContent {
+    type: LanguageModelMessageType;
+    value: LanguageModelMessageContentValue;
+}
+
+export declare type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;
+
+export declare type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
+
+export declare type LanguageModelMessageType = 'text' | 'image' | 'audio';
+
+declare type LanguageModelPrompt = LanguageModelMessage[];
+
+declare interface LanguageModelPromptOptions {
+    responseConstraint?: object;
+}
+
 /**
  * Content part modality.
  * @public
@@ -1596,6 +1799,14 @@ export declare interface ObjectSchemaInterface extends SchemaInterface {
     optionalProperties?: string[];
 }
 
+/**
+ * Encapsulates configuration for on-device inference.
+ */
+export declare interface OnDeviceParams {
+    createOptions?: LanguageModelCreateOptions;
+    promptOptions?: LanguageModelPromptOptions;
+}
+
 /**
  * Content part - includes text, image/video, or function call/response
  * part types.