Merge c16cbf1 into 39505cc

Author: gsiddh

common/api-review/ai.api.md

@@ -112,7 +112,8 @@ export class BooleanSchema extends Schema {
 
 // @public
 export class ChatSession {
-    constructor(apiSettings: ApiSettings, model: string, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
+    // Warning: (ae-forgotten-export) The symbol "ChromeAdapter" needs to be exported by the entry point index.d.ts
+    constructor(apiSettings: ApiSettings, model: string, chromeAdapter: ChromeAdapter, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
     getHistory(): Promise<Content[]>;
     // (undocumented)
     model: string;
@@ -395,8 +396,9 @@ export interface GenerativeContentBlob {
 
 // @public
 export class GenerativeModel extends AIModel {
-    constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions);
+    constructor(ai: AI, modelParams: ModelParams, chromeAdapter: ChromeAdapter, requestOptions?: RequestOptions);
     countTokens(request: CountTokensRequest | string | Array<string | Part>): Promise<CountTokensResponse>;
+    static DEFAULT_HYBRID_IN_CLOUD_MODEL: string;
     generateContent(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentResult>;
     generateContentStream(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentStreamResult>;
     // (undocumented)
@@ -418,7 +420,7 @@ export class GenerativeModel extends AIModel {
 export function getAI(app?: FirebaseApp, options?: AIOptions): AI;
 
 // @public
-export function getGenerativeModel(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions): GenerativeModel;
+export function getGenerativeModel(ai: AI, modelParams: ModelParams | HybridParams, requestOptions?: RequestOptions): GenerativeModel;
 
 // @beta
 export function getImagenModel(ai: AI, modelParams: ImagenModelParams, requestOptions?: RequestOptions): ImagenModel;
@@ -550,6 +552,13 @@ export enum HarmSeverity {
     HARM_SEVERITY_UNSUPPORTED = "HARM_SEVERITY_UNSUPPORTED"
 }
 
+// @public
+export interface HybridParams {
+    inCloudParams?: ModelParams;
+    mode: InferenceMode;
+    onDeviceParams?: OnDeviceParams;
+}
+
 // @beta
 export enum ImagenAspectRatio {
     LANDSCAPE_16x9 = "16:9",
@@ -634,6 +643,9 @@ export interface ImagenSafetySettings {
     safetyFilterLevel?: ImagenSafetyFilterLevel;
 }
 
+// @public
+export type InferenceMode = 'prefer_on_device' | 'only_on_device' | 'only_in_cloud';
+
 // @public
 export interface InlineDataPart {
     // (undocumented)
@@ -708,6 +720,18 @@ export interface ObjectSchemaInterface extends SchemaInterface {
     type: SchemaType.OBJECT;
 }
 
+// @public
+export interface OnDeviceParams {
+    // Warning: (ae-forgotten-export) The symbol "LanguageModelCreateOptions" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    createOptions?: LanguageModelCreateOptions;
+    // Warning: (ae-forgotten-export) The symbol "LanguageModelPromptOptions" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    promptOptions?: LanguageModelPromptOptions;
+}
+
 // @public
 export type Part = TextPart | InlineDataPart | FunctionCallPart | FunctionResponsePart | FileDataPart;
 

docs-devsite/_toc.yaml

@@ -80,6 +80,8 @@ toc:
     path: /docs/reference/js/ai.groundingattribution.md
   - title: GroundingMetadata
     path: /docs/reference/js/ai.groundingmetadata.md
+  - title: HybridParams
+    path: /docs/reference/js/ai.hybridparams.md
   - title: ImagenGCSImage
     path: /docs/reference/js/ai.imagengcsimage.md
   - title: ImagenGenerationConfig
@@ -110,6 +112,8 @@ toc:
     path: /docs/reference/js/ai.objectschema.md
   - title: ObjectSchemaInterface
     path: /docs/reference/js/ai.objectschemainterface.md
+  - title: OnDeviceParams
+    path: /docs/reference/js/ai.ondeviceparams.md
   - title: PromptFeedback
     path: /docs/reference/js/ai.promptfeedback.md
   - title: RequestOptions

docs-devsite/ai.chatsession.md

@@ -22,7 +22,7 @@ export declare class ChatSession
 
 |  Constructor | Modifiers | Description |
 |  --- | --- | --- |
-|  [(constructor)(apiSettings, model, params, requestOptions)](./ai.chatsession.md#chatsessionconstructor) |  | Constructs a new instance of the <code>ChatSession</code> class |
+|  [(constructor)(apiSettings, model, chromeAdapter, params, requestOptions)](./ai.chatsession.md#chatsessionconstructor) |  | Constructs a new instance of the <code>ChatSession</code> class |
 
 ## Properties
 
@@ -47,7 +47,7 @@ Constructs a new instance of the `ChatSession` class
 <b>Signature:</b>
 
 ```typescript
-constructor(apiSettings: ApiSettings, model: string, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
+constructor(apiSettings: ApiSettings, model: string, chromeAdapter: ChromeAdapter, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
 ```
 
 #### Parameters
@@ -56,6 +56,7 @@ constructor(apiSettings: ApiSettings, model: string, params?: StartChatParams |
 |  --- | --- | --- |
 |  apiSettings | ApiSettings |  |
 |  model | string |  |
+|  chromeAdapter | ChromeAdapter |  |
 |  params | [StartChatParams](./ai.startchatparams.md#startchatparams_interface) \| undefined |  |
 |  requestOptions | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) \| undefined |  |
 

docs-devsite/ai.generativemodel.md

@@ -23,12 +23,13 @@ export declare class GenerativeModel extends AIModel
 
 |  Constructor | Modifiers | Description |
 |  --- | --- | --- |
-|  [(constructor)(ai, modelParams, requestOptions)](./ai.generativemodel.md#generativemodelconstructor) |  | Constructs a new instance of the <code>GenerativeModel</code> class |
+|  [(constructor)(ai, modelParams, chromeAdapter, requestOptions)](./ai.generativemodel.md#generativemodelconstructor) |  | Constructs a new instance of the <code>GenerativeModel</code> class |
 
 ## Properties
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
+|  [DEFAULT\_HYBRID\_IN\_CLOUD\_MODEL](./ai.generativemodel.md#generativemodeldefault_hybrid_in_cloud_model) | <code>static</code> | string | Defines the name of the default in-cloud model to use for hybrid inference. |
 |  [generationConfig](./ai.generativemodel.md#generativemodelgenerationconfig) |  | [GenerationConfig](./ai.generationconfig.md#generationconfig_interface) |  |
 |  [requestOptions](./ai.generativemodel.md#generativemodelrequestoptions) |  | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) |  |
 |  [safetySettings](./ai.generativemodel.md#generativemodelsafetysettings) |  | [SafetySetting](./ai.safetysetting.md#safetysetting_interface)<!-- -->\[\] |  |
@@ -52,7 +53,7 @@ Constructs a new instance of the `GenerativeModel` class
 <b>Signature:</b>
 
 ```typescript
-constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions);
+constructor(ai: AI, modelParams: ModelParams, chromeAdapter: ChromeAdapter, requestOptions?: RequestOptions);
 ```
 
 #### Parameters
@@ -61,8 +62,19 @@ constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions);
 |  --- | --- | --- |
 |  ai | [AI](./ai.ai.md#ai_interface) |  |
 |  modelParams | [ModelParams](./ai.modelparams.md#modelparams_interface) |  |
+|  chromeAdapter | ChromeAdapter |  |
 |  requestOptions | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) |  |
 
+## GenerativeModel.DEFAULT\_HYBRID\_IN\_CLOUD\_MODEL
+
+Defines the name of the default in-cloud model to use for hybrid inference.
+
+<b>Signature:</b>
+
+```typescript
+static DEFAULT_HYBRID_IN_CLOUD_MODEL: string;
+```
+
 ## GenerativeModel.generationConfig
 
 <b>Signature:</b>

docs-devsite/ai.hybridparams.md

@@ -0,0 +1,57 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# HybridParams interface
+Toggles hybrid inference.
+
+<b>Signature:</b>
+
+```typescript
+export interface HybridParams 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [inCloudParams](./ai.hybridparams.md#hybridparamsincloudparams) | [ModelParams](./ai.modelparams.md#modelparams_interface) | Optional. Specifies advanced params for in-cloud inference. |
+|  [mode](./ai.hybridparams.md#hybridparamsmode) | [InferenceMode](./ai.md#inferencemode) | Specifies on-device or in-cloud inference. Defaults to prefer on-device. |
+|  [onDeviceParams](./ai.hybridparams.md#hybridparamsondeviceparams) | [OnDeviceParams](./ai.ondeviceparams.md#ondeviceparams_interface) | Optional. Specifies advanced params for on-device inference. |
+
+## HybridParams.inCloudParams
+
+Optional. Specifies advanced params for in-cloud inference.
+
+<b>Signature:</b>
+
+```typescript
+inCloudParams?: ModelParams;
+```
+
+## HybridParams.mode
+
+Specifies on-device or in-cloud inference. Defaults to prefer on-device.
+
+<b>Signature:</b>
+
+```typescript
+mode: InferenceMode;
+```
+
+## HybridParams.onDeviceParams
+
+Optional. Specifies advanced params for on-device inference.
+
+<b>Signature:</b>
+
+```typescript
+onDeviceParams?: OnDeviceParams;
+```

docs-devsite/ai.md

@@ -20,7 +20,7 @@ The Firebase AI Web SDK.
 |  [getAI(app, options)](./ai.md#getai_a94a413) | Returns the default [AI](./ai.ai.md#ai_interface) instance that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface)<!-- -->. If no instance exists, initializes a new instance with the default settings. |
 |  [getVertexAI(app, options)](./ai.md#getvertexai_04094cf) |  |
 |  <b>function(ai, ...)</b> |
-|  [getGenerativeModel(ai, modelParams, requestOptions)](./ai.md#getgenerativemodel_80bd839) | Returns a [GenerativeModel](./ai.generativemodel.md#generativemodel_class) class with methods for inference and other functionality. |
+|  [getGenerativeModel(ai, modelParams, requestOptions)](./ai.md#getgenerativemodel_c63f46a) | Returns a [GenerativeModel](./ai.generativemodel.md#generativemodel_class) class with methods for inference and other functionality. |
 |  [getImagenModel(ai, modelParams, requestOptions)](./ai.md#getimagenmodel_e1f6645) | <b><i>(Public Preview)</i></b> Returns an [ImagenModel](./ai.imagenmodel.md#imagenmodel_class) class with methods for using Imagen.<!-- -->Only Imagen 3 models (named <code>imagen-3.0-*</code>) are supported. |
 
 ## Classes
@@ -97,6 +97,7 @@ The Firebase AI Web SDK.
 |  [GenerativeContentBlob](./ai.generativecontentblob.md#generativecontentblob_interface) | Interface for sending an image. |
 |  [GroundingAttribution](./ai.groundingattribution.md#groundingattribution_interface) |  |
 |  [GroundingMetadata](./ai.groundingmetadata.md#groundingmetadata_interface) | Metadata returned to client when grounding is enabled. |
+|  [HybridParams](./ai.hybridparams.md#hybridparams_interface) | Toggles hybrid inference. |
 |  [ImagenGCSImage](./ai.imagengcsimage.md#imagengcsimage_interface) | An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.<!-- -->This feature is not available yet. |
 |  [ImagenGenerationConfig](./ai.imagengenerationconfig.md#imagengenerationconfig_interface) | <b><i>(Public Preview)</i></b> Configuration options for generating images with Imagen.<!-- -->See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images-imagen) for more details. |
 |  [ImagenGenerationResponse](./ai.imagengenerationresponse.md#imagengenerationresponse_interface) | <b><i>(Public Preview)</i></b> The response from a request to generate images with Imagen. |
@@ -105,10 +106,11 @@ The Firebase AI Web SDK.
 |  [ImagenSafetySettings](./ai.imagensafetysettings.md#imagensafetysettings_interface) | <b><i>(Public Preview)</i></b> Settings for controlling the aggressiveness of filtering out sensitive content.<!-- -->See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details. |
 |  [InlineDataPart](./ai.inlinedatapart.md#inlinedatapart_interface) | Content part interface if the part represents an image. |
 |  [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface) | Represents token counting info for a single modality. |
-|  [ModelParams](./ai.modelparams.md#modelparams_interface) | Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_80bd839)<!-- -->. |
+|  [ModelParams](./ai.modelparams.md#modelparams_interface) | Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_c63f46a)<!-- -->. |
 |  [ObjectSchemaInterface](./ai.objectschemainterface.md#objectschemainterface_interface) | Interface for [ObjectSchema](./ai.objectschema.md#objectschema_class) class. |
+|  [OnDeviceParams](./ai.ondeviceparams.md#ondeviceparams_interface) | Encapsulates configuration for on-device inference. |
 |  [PromptFeedback](./ai.promptfeedback.md#promptfeedback_interface) | If the prompt was blocked, this will be populated with <code>blockReason</code> and the relevant <code>safetyRatings</code>. |
-|  [RequestOptions](./ai.requestoptions.md#requestoptions_interface) | Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_80bd839)<!-- -->. |
+|  [RequestOptions](./ai.requestoptions.md#requestoptions_interface) | Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_c63f46a)<!-- -->. |
 |  [RetrievedContextAttribution](./ai.retrievedcontextattribution.md#retrievedcontextattribution_interface) |  |
 |  [SafetyRating](./ai.safetyrating.md#safetyrating_interface) | A safety rating associated with a [GenerateContentCandidate](./ai.generatecontentcandidate.md#generatecontentcandidate_interface) |
 |  [SafetySetting](./ai.safetysetting.md#safetysetting_interface) | Safety setting that can be sent as part of request parameters. |
@@ -140,6 +142,7 @@ The Firebase AI Web SDK.
 |  Type Alias | Description |
 |  --- | --- |
 |  [BackendType](./ai.md#backendtype) | Type alias representing valid backend types. It can be either <code>'VERTEX_AI'</code> or <code>'GOOGLE_AI'</code>. |
+|  [InferenceMode](./ai.md#inferencemode) | Determines whether inference happens on-device or in-cloud. |
 |  [Part](./ai.md#part) | Content part - includes text, image/video, or function call/response part types. |
 |  [ResponseModality](./ai.md#responsemodality) | <b><i>(Public Preview)</i></b> Generation modalities to be returned in generation responses. |
 |  [Role](./ai.md#role) | Role is the producer of the content. |
@@ -226,22 +229,22 @@ export declare function getVertexAI(app?: FirebaseApp, options?: VertexAIOptions
 
 ## function(ai, ...)
 
-### getGenerativeModel(ai, modelParams, requestOptions) {:#getgenerativemodel_80bd839}
+### getGenerativeModel(ai, modelParams, requestOptions) {:#getgenerativemodel_c63f46a}
 
 Returns a [GenerativeModel](./ai.generativemodel.md#generativemodel_class) class with methods for inference and other functionality.
 
 <b>Signature:</b>
 
 ```typescript
-export declare function getGenerativeModel(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions): GenerativeModel;
+export declare function getGenerativeModel(ai: AI, modelParams: ModelParams | HybridParams, requestOptions?: RequestOptions): GenerativeModel;
 ```
 
 #### Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  ai | [AI](./ai.ai.md#ai_interface) |  |
-|  modelParams | [ModelParams](./ai.modelparams.md#modelparams_interface) |  |
+|  modelParams | [ModelParams](./ai.modelparams.md#modelparams_interface) \| [HybridParams](./ai.hybridparams.md#hybridparams_interface) |  |
 |  requestOptions | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) |  |
 
 <b>Returns:</b>
@@ -360,6 +363,16 @@ Type alias representing valid backend types. It can be either `'VERTEX_AI'` or `
 export type BackendType = (typeof BackendType)[keyof typeof BackendType];
 ```
 
+## InferenceMode
+
+Determines whether inference happens on-device or in-cloud.
+
+<b>Signature:</b>
+
+```typescript
+export type InferenceMode = 'prefer_on_device' | 'only_on_device' | 'only_in_cloud';
+```
+
 ## Part
 
 Content part - includes text, image/video, or function call/response part types.

docs-devsite/ai.modelparams.md

@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # ModelParams interface
-Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_80bd839)<!-- -->.
+Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_c63f46a)<!-- -->.
 
 <b>Signature:</b>
 

docs-devsite/ai.ondeviceparams.md

@@ -0,0 +1,42 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# OnDeviceParams interface
+Encapsulates configuration for on-device inference.
+
+<b>Signature:</b>
+
+```typescript
+export interface OnDeviceParams 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [createOptions](./ai.ondeviceparams.md#ondeviceparamscreateoptions) | LanguageModelCreateOptions |  |
+|  [promptOptions](./ai.ondeviceparams.md#ondeviceparamspromptoptions) | LanguageModelPromptOptions |  |
+
+## OnDeviceParams.createOptions
+
+<b>Signature:</b>
+
+```typescript
+createOptions?: LanguageModelCreateOptions;
+```
+
+## OnDeviceParams.promptOptions
+
+<b>Signature:</b>
+
+```typescript
+promptOptions?: LanguageModelPromptOptions;
+```

docs-devsite/ai.requestoptions.md

@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # RequestOptions interface
-Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_80bd839)<!-- -->.
+Params passed to [getGenerativeModel()](./ai.md#getgenerativemodel_c63f46a)<!-- -->.
 
 <b>Signature:</b>
 

packages/ai/src/api.test.ts

@@ -102,6 +102,21 @@ describe('Top level API', () => {
     expect(genModel).to.be.an.instanceOf(GenerativeModel);
     expect(genModel.model).to.equal('publishers/google/models/my-model');
   });
+  it('getGenerativeModel with HybridParams sets a default model', () => {
+    const genModel = getGenerativeModel(fakeAI, {
+      mode: 'only_on_device'
+    });
+    expect(genModel.model).to.equal(
+      `publishers/google/models/${GenerativeModel.DEFAULT_HYBRID_IN_CLOUD_MODEL}`
+    );
+  });
+  it('getGenerativeModel with HybridParams honors a model override', () => {
+    const genModel = getGenerativeModel(fakeAI, {
+      mode: 'prefer_on_device',
+      inCloudParams: { model: 'my-model' }
+    });
+    expect(genModel.model).to.equal('publishers/google/models/my-model');
+  });
   it('getImagenModel throws if no model is provided', () => {
     try {
       getImagenModel(fakeAI, {} as ImagenModelParams);