Merge branch 'erikeldridge-vertex-api' into erikeldridge-vertex-adapter

Author: erikeldridge

common/api-review/vertexai.api.md

@@ -327,6 +327,7 @@ export interface GenerativeContentBlob {
 export class GenerativeModel extends VertexAIModel {
     constructor(vertexAI: VertexAI, 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)
@@ -419,8 +420,8 @@ export enum HarmSeverity {
 
 // @public
 export interface HybridParams {
-    mode?: InferenceMode;
-    onCloudParams?: ModelParams;
+    inCloudParams?: ModelParams;
+    mode: InferenceMode;
     onDeviceParams?: AILanguageModelCreateOptionsWithSystemPrompt;
 }
 
@@ -509,11 +510,7 @@ export interface ImagenSafetySettings {
 }
 
 // @public
-export enum InferenceMode {
-    ONLY_ON_CLOUD = "ONLY_ON_CLOUD",
-    ONLY_ON_DEVICE = "ONLY_ON_DEVICE",
-    PREFER_ON_DEVICE = "PREFER_ON_DEVICE"
-}
+export type InferenceMode = 'prefer_on_device' | 'only_on_device' | 'only_in_cloud';
 
 // @public
 export interface InlineDataPart {

docs-devsite/vertexai.generativemodel.md

@@ -29,6 +29,7 @@ export declare class GenerativeModel extends VertexAIModel
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
+|  [DEFAULT\_HYBRID\_IN\_CLOUD\_MODEL](./vertexai.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](./vertexai.generativemodel.md#generativemodelgenerationconfig) |  | [GenerationConfig](./vertexai.generationconfig.md#generationconfig_interface) |  |
 |  [requestOptions](./vertexai.generativemodel.md#generativemodelrequestoptions) |  | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) |  |
 |  [safetySettings](./vertexai.generativemodel.md#generativemodelsafetysettings) |  | [SafetySetting](./vertexai.safetysetting.md#safetysetting_interface)<!-- -->\[\] |  |
@@ -63,6 +64,16 @@ constructor(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: Reque
 |  modelParams | [ModelParams](./vertexai.modelparams.md#modelparams_interface) |  |
 |  requestOptions | [RequestOptions](./vertexai.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/vertexai.hybridparams.md

@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # HybridParams interface
-Configures on-device and on-cloud inference.
+Toggles hybrid inference.
 
 <b>Signature:</b>
 
@@ -22,28 +22,28 @@ export interface HybridParams
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [mode](./vertexai.hybridparams.md#hybridparamsmode) | [InferenceMode](./vertexai.md#inferencemode) | Optional. Specifies on-device or on-cloud inference. Defaults to prefer on-device. |
-|  [onCloudParams](./vertexai.hybridparams.md#hybridparamsoncloudparams) | [ModelParams](./vertexai.modelparams.md#modelparams_interface) | Optional. Specifies advanced params for on-cloud inference. |
+|  [inCloudParams](./vertexai.hybridparams.md#hybridparamsincloudparams) | [ModelParams](./vertexai.modelparams.md#modelparams_interface) | Optional. Specifies advanced params for in-cloud inference. |
+|  [mode](./vertexai.hybridparams.md#hybridparamsmode) | [InferenceMode](./vertexai.md#inferencemode) | Specifies on-device or in-cloud inference. Defaults to prefer on-device. |
 |  [onDeviceParams](./vertexai.hybridparams.md#hybridparamsondeviceparams) | AILanguageModelCreateOptionsWithSystemPrompt | Optional. Specifies advanced params for on-device inference. |
 
-## HybridParams.mode
+## HybridParams.inCloudParams
 
-Optional. Specifies on-device or on-cloud inference. Defaults to prefer on-device.
+Optional. Specifies advanced params for in-cloud inference.
 
 <b>Signature:</b>
 
 ```typescript
-mode?: InferenceMode;
+inCloudParams?: ModelParams;
 ```
 
-## HybridParams.onCloudParams
+## HybridParams.mode
 
-Optional. Specifies advanced params for on-cloud inference.
+Specifies on-device or in-cloud inference. Defaults to prefer on-device.
 
 <b>Signature:</b>
 
 ```typescript
-onCloudParams?: ModelParams;
+mode: InferenceMode;
 ```
 
 ## HybridParams.onDeviceParams

docs-devsite/vertexai.md

@@ -55,7 +55,6 @@ The Vertex AI in Firebase Web SDK.
 |  [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | <b><i>(Public Preview)</i></b> Aspect ratios for Imagen images.<!-- -->To specify an aspect ratio for generated images, set the <code>aspectRatio</code> property in your <code>[ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface)</code>.<!-- -->See the the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. |
 |  [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel) | <b><i>(Public Preview)</i></b> A filter level controlling whether generation of images containing people or faces is allowed.<!-- -->See the <a href="http://firebase.google.com/docs/vertex-ai/generate-images"><code>personGeneration</code></a> documentation for more details. |
 |  [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel) | <b><i>(Public Preview)</i></b> A filter level controlling how aggressively to filter sensitive content.<!-- -->Text prompts provided as inputs and images (generated or uploaded) through Imagen on Vertex AI are assessed against a list of safety filters, which include 'harmful categories' (for example, <code>violence</code>, <code>sexual</code>, <code>derogatory</code>, and <code>toxic</code>). This filter level controls how aggressively to filter out potentially harmful content from responses. See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) and the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters) for more details. |
-|  [InferenceMode](./vertexai.md#inferencemode) | Determines whether inference happens on-device or on-cloud. |
 |  [Modality](./vertexai.md#modality) | Content part modality. |
 |  [SchemaType](./vertexai.md#schematype) | Contains the list of OpenAPI data types as defined by the [OpenAPI specification](https://swagger.io/docs/specification/data-models/data-types/) |
 |  [VertexAIErrorCode](./vertexai.md#vertexaierrorcode) | Standardized error codes that <code>[VertexAIError](./vertexai.vertexaierror.md#vertexaierror_class)</code> can have. |
@@ -92,7 +91,7 @@ The Vertex AI in Firebase Web SDK.
 |  [GenerativeContentBlob](./vertexai.generativecontentblob.md#generativecontentblob_interface) | Interface for sending an image. |
 |  [GroundingAttribution](./vertexai.groundingattribution.md#groundingattribution_interface) |  |
 |  [GroundingMetadata](./vertexai.groundingmetadata.md#groundingmetadata_interface) | Metadata returned to client when grounding is enabled. |
-|  [HybridParams](./vertexai.hybridparams.md#hybridparams_interface) | Configures on-device and on-cloud inference. |
+|  [HybridParams](./vertexai.hybridparams.md#hybridparams_interface) | Toggles hybrid inference. |
 |  [ImagenGCSImage](./vertexai.imagengcsimage.md#imagengcsimage_interface) | An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.<!-- -->This feature is not available yet. |
 |  [ImagenGenerationConfig](./vertexai.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](./vertexai.imagengenerationresponse.md#imagengenerationresponse_interface) | <b><i>(Public Preview)</i></b> The response from a request to generate images with Imagen. |
@@ -132,6 +131,7 @@ The Vertex AI in Firebase Web SDK.
 
 |  Type Alias | Description |
 |  --- | --- |
+|  [InferenceMode](./vertexai.md#inferencemode) | Determines whether inference happens on-device or in-cloud. |
 |  [Part](./vertexai.md#part) | Content part - includes text, image/video, or function call/response part types. |
 |  [Role](./vertexai.md#role) | Role is the producer of the content. |
 |  [Tool](./vertexai.md#tool) | Defines a tool that model can call to access external knowledge. |
@@ -225,6 +225,16 @@ Possible roles.
 POSSIBLE_ROLES: readonly ["user", "model", "function", "system"]
 ```
 
+## 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.
@@ -491,24 +501,6 @@ export declare enum ImagenSafetyFilterLevel
 |  BLOCK\_NONE | <code>&quot;block_none&quot;</code> | <b><i>(Public Preview)</i></b> The least aggressive filtering level; blocks very few sensitive prompts and responses.<!-- -->Access to this feature is restricted and may require your case to be reviewed and approved by Cloud support. |
 |  BLOCK\_ONLY\_HIGH | <code>&quot;block_only_high&quot;</code> | <b><i>(Public Preview)</i></b> Blocks few sensitive prompts and responses. |
 
-## InferenceMode
-
-Determines whether inference happens on-device or on-cloud.
-
-<b>Signature:</b>
-
-```typescript
-export declare enum InferenceMode 
-```
-
-## Enumeration Members
-
-|  Member | Value | Description |
-|  --- | --- | --- |
-|  ONLY\_ON\_CLOUD | <code>&quot;ONLY_ON_CLOUD&quot;</code> | Exclusively uses the on-cloud model. |
-|  ONLY\_ON\_DEVICE | <code>&quot;ONLY_ON_DEVICE&quot;</code> | Exclusively uses the on-device model. Throws if one is not available. |
-|  PREFER\_ON\_DEVICE | <code>&quot;PREFER_ON_DEVICE&quot;</code> | Uses the on-device model if available, or falls back to the on-cloud model. |
-
 ## Modality
 
 Content part modality.

packages/vertexai/src/api.test.ts

@@ -16,7 +16,6 @@
  */
 import {
   ImagenModelParams,
-  InferenceMode,
   ModelParams,
   VertexAIErrorCode
 } from './types';
@@ -106,10 +105,18 @@ 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 the model', () => {
+  it('getGenerativeModel with HybridParams sets a default model', () => {
     const genModel = getGenerativeModel(fakeVertexAI, {
-      mode: InferenceMode.ONLY_ON_CLOUD,
-      onCloudParams: { model: 'my-model' }
+      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(fakeVertexAI, {
+      mode: 'only_in_cloud',
+      inCloudParams: { model: 'my-model' }
     });
     expect(genModel.model).to.equal('publishers/google/models/my-model');
   });

packages/vertexai/src/api.ts

@@ -77,24 +77,24 @@ export function getGenerativeModel(
 ): GenerativeModel {
   // Uses the existence of HybridParams.mode to clarify the type of the modelParams input.
   const hybridParams = modelParams as HybridParams;
-  let onCloudParams: ModelParams;
+  let inCloudParams: ModelParams;
   if (hybridParams.mode) {
-    onCloudParams = hybridParams.onCloudParams || {
-      model: 'gemini-2.0-flash-lite'
+    inCloudParams = hybridParams.inCloudParams || {
+      model: GenerativeModel.DEFAULT_HYBRID_IN_CLOUD_MODEL
     };
   } else {
-    onCloudParams = modelParams as ModelParams;
+    inCloudParams = modelParams as ModelParams;
   }
 
-  if (!onCloudParams.model) {
+  if (!inCloudParams.model) {
     throw new VertexAIError(
       VertexAIErrorCode.NO_MODEL,
       `Must provide a model name. Example: getGenerativeModel({ model: 'my-model-name' })`
     );
   }
   return new GenerativeModel(
     vertexAI,
-    onCloudParams,
+    inCloudParams,
     new ChromeAdapter(
       window.ai as AI,
       hybridParams.mode,

packages/vertexai/src/models/generative-model.ts

@@ -50,6 +50,10 @@ import { ChromeAdapter } from '../methods/chrome-adapter';
  * @public
  */
 export class GenerativeModel extends VertexAIModel {
+  /**
+   * Defines the name of the default in-cloud model to use for hybrid inference.
+   */
+  static DEFAULT_HYBRID_IN_CLOUD_MODEL = 'gemini-2.0-flash-lite';
   generationConfig: GenerationConfig;
   safetySettings: SafetySetting[];
   requestOptions?: RequestOptions;

packages/vertexai/src/types/enums.ts

@@ -240,24 +240,3 @@ export enum Modality {
    */
   DOCUMENT = 'DOCUMENT'
 }
-
-/**
- * Determines whether inference happens on-device or on-cloud.
- * @public
- */
-export enum InferenceMode {
-  /**
-   * Uses the on-device model if available, or falls back to the on-cloud model.
-   */
-  PREFER_ON_DEVICE = 'PREFER_ON_DEVICE',
-
-  /**
-   * Exclusively uses the on-device model. Throws if one is not available.
-   */
-  ONLY_ON_DEVICE = 'ONLY_ON_DEVICE',
-
-  /**
-   * Exclusively uses the on-cloud model.
-   */
-  ONLY_ON_CLOUD = 'ONLY_ON_CLOUD'
-}

packages/vertexai/src/types/requests.ts

@@ -21,8 +21,7 @@ import {
   FunctionCallingMode,
   HarmBlockMethod,
   HarmBlockThreshold,
-  HarmCategory,
-  InferenceMode
+  HarmCategory
 } from './enums';
 import { ObjectSchemaInterface, SchemaRequest } from './schema';
 
@@ -216,20 +215,26 @@ export interface FunctionCallingConfig {
 }
 
 /**
- * Configures on-device and on-cloud inference.
- * @public
+ * Toggles hybrid inference.
  */
 export interface HybridParams {
   /**
-   * Optional. Specifies on-device or on-cloud inference. Defaults to prefer on-device.
+   * Specifies on-device or in-cloud inference. Defaults to prefer on-device.
    */
-  mode?: InferenceMode;
+  mode: InferenceMode;
   /**
    * Optional. Specifies advanced params for on-device inference.
    */
   onDeviceParams?: AILanguageModelCreateOptionsWithSystemPrompt;
   /**
-   * Optional. Specifies advanced params for on-cloud inference.
+   * Optional. Specifies advanced params for in-cloud inference.
    */
-  onCloudParams?: ModelParams;
+  inCloudParams?: ModelParams;
 }
+/**
+ * Determines whether inference happens on-device or in-cloud.
+ */
+export type InferenceMode =
+  | 'prefer_on_device'
+  | 'only_on_device'
+  | 'only_in_cloud';