Ensure EXPERIMENTAL added to doc comments, fill out doc comments

hsubox76 · hsubox76 · commit 9e4e910d9f15 · 2025-07-30T15:32:09.000-07:00
diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md
@@ -430,7 +430,6 @@ export interface GenerativeContentBlob {
 export class GenerativeModel extends AIModel {
     constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions, chromeAdapter?: ChromeAdapter | undefined);
     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)
@@ -729,7 +728,7 @@ export class IntegerSchema extends Schema {
     constructor(schemaParams?: SchemaParams);
 }
 
-// @public (undocumented)
+// @public
 export interface LanguageModelCreateCoreOptions {
     // (undocumented)
     expectedInputs?: LanguageModelExpected[];
@@ -739,48 +738,48 @@ export interface LanguageModelCreateCoreOptions {
     topK?: number;
 }
 
-// @public (undocumented)
+// @public
 export interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
     // (undocumented)
     initialPrompts?: LanguageModelMessage[];
     // (undocumented)
     signal?: AbortSignal;
 }
 
-// @public (undocumented)
+// @public
 export interface LanguageModelExpected {
     // (undocumented)
     languages?: string[];
     // (undocumented)
     type: LanguageModelMessageType;
 }
 
-// @public (undocumented)
+// @public
 export interface LanguageModelMessage {
     // (undocumented)
     content: LanguageModelMessageContent[];
     // (undocumented)
     role: LanguageModelMessageRole;
 }
 
-// @public (undocumented)
+// @public
 export interface LanguageModelMessageContent {
     // (undocumented)
     type: LanguageModelMessageType;
     // (undocumented)
     value: LanguageModelMessageContentValue;
 }
 
-// @public (undocumented)
+// @public
 export type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;
 
-// @public (undocumented)
+// @public
 export type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
 
-// @public (undocumented)
+// @public
 export type LanguageModelMessageType = 'text' | 'image' | 'audio';
 
-// @public (undocumented)
+// @public
 export interface LanguageModelPromptOptions {
     // (undocumented)
     responseConstraint?: object;
diff --git a/docs-devsite/ai.generativemodel.md b/docs-devsite/ai.generativemodel.md
@@ -29,7 +29,6 @@ export declare class GenerativeModel extends AIModel
 
 |  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)<!-- -->\[\] |  |
@@ -65,16 +64,6 @@ constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions, c
 |  requestOptions | [RequestOptions](./ai.requestoptions.md#requestoptions_interface) |  |
 |  chromeAdapter | [ChromeAdapter](./ai.chromeadapter.md#chromeadapter_interface) \| undefined |  |
 
-## 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>
diff --git a/docs-devsite/ai.hybridparams.md b/docs-devsite/ai.hybridparams.md
@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # HybridParams interface
-Configures hybrid inference.
+(EXPERIMENTAL) Configures hybrid inference.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.languagemodelcreatecoreoptions.md b/docs-devsite/ai.languagemodelcreatecoreoptions.md
@@ -10,6 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # LanguageModelCreateCoreOptions interface
+(EXPERIMENTAL) Used to configure the creation of an on-device language model session.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.languagemodelcreateoptions.md b/docs-devsite/ai.languagemodelcreateoptions.md
@@ -10,6 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # LanguageModelCreateOptions interface
+(EXPERIMENTAL) Used to configure the creation of an on-device language model session.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.languagemodelexpected.md b/docs-devsite/ai.languagemodelexpected.md
@@ -10,6 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # LanguageModelExpected interface
+(EXPERIMENTAL) Options for an on-device language model expected inputs.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.languagemodelmessage.md b/docs-devsite/ai.languagemodelmessage.md
@@ -10,6 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # LanguageModelMessage interface
+(EXPERIMENTAL) An on-device language model message.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.languagemodelmessagecontent.md b/docs-devsite/ai.languagemodelmessagecontent.md
@@ -10,6 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # LanguageModelMessageContent interface
+(EXPERIMENTAL) An on-device language model content object.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.languagemodelpromptoptions.md b/docs-devsite/ai.languagemodelpromptoptions.md
@@ -10,6 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # LanguageModelPromptOptions interface
+(EXPERIMENTAL) Options for an on-device language model prompt.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.md b/docs-devsite/ai.md
@@ -82,24 +82,24 @@ The Firebase AI Web SDK.
 |  [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface) | Represents a chunk of retrieved data that supports a claim in the model's response. This is part of the grounding information provided when grounding is enabled. |
 |  [GroundingMetadata](./ai.groundingmetadata.md#groundingmetadata_interface) | Metadata returned when grounding is enabled.<!-- -->Currently, only Grounding with Google Search is supported (see [GoogleSearchTool](./ai.googlesearchtool.md#googlesearchtool_interface)<!-- -->).<!-- -->Important: If using Grounding with Google Search, you are required to comply with the "Grounding with Google Search" usage requirements for your chosen API provider: [Gemini Developer API](https://ai.google.dev/gemini-api/terms#grounding-with-google-search) or Vertex AI Gemini API (see [Service Terms](https://cloud.google.com/terms/service-terms) section within the Service Specific Terms). |
 |  [GroundingSupport](./ai.groundingsupport.md#groundingsupport_interface) | Provides information about how a specific segment of the model's response is supported by the retrieved grounding chunks. |
-|  [HybridParams](./ai.hybridparams.md#hybridparams_interface) | Configures hybrid inference. |
+|  [HybridParams](./ai.hybridparams.md#hybridparams_interface) | (EXPERIMENTAL) Configures hybrid inference. |
 |  [ImagenGCSImage](./ai.imagengcsimage.md#imagengcsimage_interface) | <b><i>(Public Preview)</i></b> 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. |
 |  [ImagenInlineImage](./ai.imageninlineimage.md#imageninlineimage_interface) | <b><i>(Public Preview)</i></b> An image generated by Imagen, represented as inline data. |
 |  [ImagenModelParams](./ai.imagenmodelparams.md#imagenmodelparams_interface) | <b><i>(Public Preview)</i></b> Parameters for configuring an [ImagenModel](./ai.imagenmodel.md#imagenmodel_class)<!-- -->. |
 |  [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. |
-|  [LanguageModelCreateCoreOptions](./ai.languagemodelcreatecoreoptions.md#languagemodelcreatecoreoptions_interface) |  |
-|  [LanguageModelCreateOptions](./ai.languagemodelcreateoptions.md#languagemodelcreateoptions_interface) |  |
-|  [LanguageModelExpected](./ai.languagemodelexpected.md#languagemodelexpected_interface) |  |
-|  [LanguageModelMessage](./ai.languagemodelmessage.md#languagemodelmessage_interface) |  |
-|  [LanguageModelMessageContent](./ai.languagemodelmessagecontent.md#languagemodelmessagecontent_interface) |  |
-|  [LanguageModelPromptOptions](./ai.languagemodelpromptoptions.md#languagemodelpromptoptions_interface) |  |
+|  [LanguageModelCreateCoreOptions](./ai.languagemodelcreatecoreoptions.md#languagemodelcreatecoreoptions_interface) | (EXPERIMENTAL) Used to configure the creation of an on-device language model session. |
+|  [LanguageModelCreateOptions](./ai.languagemodelcreateoptions.md#languagemodelcreateoptions_interface) | (EXPERIMENTAL) Used to configure the creation of an on-device language model session. |
+|  [LanguageModelExpected](./ai.languagemodelexpected.md#languagemodelexpected_interface) | (EXPERIMENTAL) Options for an on-device language model expected inputs. |
+|  [LanguageModelMessage](./ai.languagemodelmessage.md#languagemodelmessage_interface) | (EXPERIMENTAL) An on-device language model message. |
+|  [LanguageModelMessageContent](./ai.languagemodelmessagecontent.md#languagemodelmessagecontent_interface) | (EXPERIMENTAL) An on-device language model content object. |
+|  [LanguageModelPromptOptions](./ai.languagemodelpromptoptions.md#languagemodelpromptoptions_interface) | (EXPERIMENTAL) Options for an on-device language model prompt. |
 |  [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_c63f46a)<!-- -->. |
 |  [ObjectSchemaRequest](./ai.objectschemarequest.md#objectschemarequest_interface) | Interface for JSON parameters in a schema of [SchemaType](./ai.md#schematype) "object" when not using the <code>Schema.object()</code> helper. |
-|  [OnDeviceParams](./ai.ondeviceparams.md#ondeviceparams_interface) | Encapsulates configuration for on-device inference. |
+|  [OnDeviceParams](./ai.ondeviceparams.md#ondeviceparams_interface) | (EXPERIMENTAL) 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_c63f46a)<!-- -->. |
 |  [RetrievedContextAttribution](./ai.retrievedcontextattribution.md#retrievedcontextattribution_interface) |  |
@@ -137,7 +137,7 @@ The Firebase AI Web SDK.
 |  [ImagenAspectRatio](./ai.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 [ImagenGenerationConfig](./ai.imagengenerationconfig.md#imagengenerationconfig_interface)<!-- -->.<!-- -->See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. |
 |  [ImagenPersonFilterLevel](./ai.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">personGeneration</a> documentation for more details. |
 |  [ImagenSafetyFilterLevel](./ai.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](./ai.md#inferencemode) | EXPERIMENTAL FEATURE Determines whether inference happens on-device or in-cloud. |
+|  [InferenceMode](./ai.md#inferencemode) | (EXPERIMENTAL) Determines whether inference happens on-device or in-cloud. |
 |  [Modality](./ai.md#modality) | Content part modality. |
 |  [POSSIBLE\_ROLES](./ai.md#possible_roles) | Possible roles. |
 |  [ResponseModality](./ai.md#responsemodality) | <b><i>(Public Preview)</i></b> Generation modalities to be returned in generation responses. |
@@ -160,10 +160,10 @@ The Firebase AI Web SDK.
 |  [ImagenAspectRatio](./ai.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 [ImagenGenerationConfig](./ai.imagengenerationconfig.md#imagengenerationconfig_interface)<!-- -->.<!-- -->See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. |
 |  [ImagenPersonFilterLevel](./ai.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">personGeneration</a> documentation for more details. |
 |  [ImagenSafetyFilterLevel](./ai.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](./ai.md#inferencemode) | EXPERIMENTAL FEATURE Determines whether inference happens on-device or in-cloud. |
-|  [LanguageModelMessageContentValue](./ai.md#languagemodelmessagecontentvalue) |  |
-|  [LanguageModelMessageRole](./ai.md#languagemodelmessagerole) |  |
-|  [LanguageModelMessageType](./ai.md#languagemodelmessagetype) |  |
+|  [InferenceMode](./ai.md#inferencemode) | (EXPERIMENTAL) Determines whether inference happens on-device or in-cloud. |
+|  [LanguageModelMessageContentValue](./ai.md#languagemodelmessagecontentvalue) | (EXPERIMENTAL) Content formats that can be provided as on-device message content. |
+|  [LanguageModelMessageRole](./ai.md#languagemodelmessagerole) | (EXPERIMENTAL) Allowable roles for on-device language model usage. |
+|  [LanguageModelMessageType](./ai.md#languagemodelmessagetype) | (EXPERIMENTAL) Allowable types for on-device language model messages. |
 |  [Modality](./ai.md#modality) | Content part modality. |
 |  [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. |
@@ -504,7 +504,7 @@ ImagenSafetyFilterLevel: {
 
 ## InferenceMode
 
-EXPERIMENTAL FEATURE Determines whether inference happens on-device or in-cloud.
+(EXPERIMENTAL) Determines whether inference happens on-device or in-cloud.
 
 <b>Signature:</b>
 
@@ -724,7 +724,7 @@ export type ImagenSafetyFilterLevel = (typeof ImagenSafetyFilterLevel)[keyof typ
 
 ## InferenceMode
 
-EXPERIMENTAL FEATURE Determines whether inference happens on-device or in-cloud.
+(EXPERIMENTAL) Determines whether inference happens on-device or in-cloud.
 
 <b>Signature:</b>
 
@@ -734,6 +734,7 @@ export type InferenceMode = (typeof InferenceMode)[keyof typeof InferenceMode];
 
 ## LanguageModelMessageContentValue
 
+(EXPERIMENTAL) Content formats that can be provided as on-device message content.
 
 <b>Signature:</b>
 
@@ -743,6 +744,7 @@ export type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer |
 
 ## LanguageModelMessageRole
 
+(EXPERIMENTAL) Allowable roles for on-device language model usage.
 
 <b>Signature:</b>
 
@@ -752,6 +754,7 @@ export type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
 
 ## LanguageModelMessageType
 
+(EXPERIMENTAL) Allowable types for on-device language model messages.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.ondeviceparams.md b/docs-devsite/ai.ondeviceparams.md
@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # OnDeviceParams interface
-Encapsulates configuration for on-device inference.
+(EXPERIMENTAL) Encapsulates configuration for on-device inference.
 
 <b>Signature:</b>
 
diff --git a/packages/ai/src/api.test.ts b/packages/ai/src/api.test.ts
@@ -21,7 +21,7 @@ import { expect } from 'chai';
 import { AI } from './public-types';
 import { GenerativeModel } from './models/generative-model';
 import { VertexAIBackend } from './backend';
-import { AI_TYPE } from './constants';
+import { AI_TYPE, DEFAULT_HYBRID_IN_CLOUD_MODEL } from './constants';
 
 const fakeAI: AI = {
   app: {
@@ -107,7 +107,7 @@ describe('Top level API', () => {
       mode: 'only_on_device'
     });
     expect(genModel.model).to.equal(
-      `publishers/google/models/${GenerativeModel.DEFAULT_HYBRID_IN_CLOUD_MODEL}`
+      `publishers/google/models/${DEFAULT_HYBRID_IN_CLOUD_MODEL}`
     );
   });
   it('getGenerativeModel with HybridParams honors a model override', () => {
diff --git a/packages/ai/src/api.ts b/packages/ai/src/api.ts
@@ -18,7 +18,7 @@
 import { FirebaseApp, getApp, _getProvider } from '@firebase/app';
 import { Provider } from '@firebase/component';
 import { getModularInstance } from '@firebase/util';
-import { AI_TYPE } from './constants';
+import { AI_TYPE, DEFAULT_HYBRID_IN_CLOUD_MODEL } from './constants';
 import { AIService } from './service';
 import { AI, AIOptions } from './public-types';
 import {
@@ -105,7 +105,7 @@ export function getGenerativeModel(
   let inCloudParams: ModelParams;
   if (hybridParams.mode) {
     inCloudParams = hybridParams.inCloudParams || {
-      model: GenerativeModel.DEFAULT_HYBRID_IN_CLOUD_MODEL
+      model: DEFAULT_HYBRID_IN_CLOUD_MODEL
     };
   } else {
     inCloudParams = modelParams as ModelParams;
@@ -118,6 +118,7 @@ export function getGenerativeModel(
     );
   }
   let chromeAdapter: ChromeAdapterImpl | undefined;
+  // Do not initialize a ChromeAdapter if we are not in hybrid mode.
   if (typeof window !== 'undefined' && hybridParams.mode) {
     chromeAdapter = new ChromeAdapterImpl(
       window.LanguageModel as LanguageModel,
diff --git a/packages/ai/src/constants.ts b/packages/ai/src/constants.ts
@@ -30,3 +30,8 @@ export const PACKAGE_VERSION = version;
 export const LANGUAGE_TAG = 'gl-js';
 
 export const DEFAULT_FETCH_TIMEOUT_MS = 180 * 1000;
+
+/**
+ * Defines the name of the default in-cloud model to use for hybrid inference.
+ */
+export const DEFAULT_HYBRID_IN_CLOUD_MODEL = 'gemini-2.0-flash-lite';
diff --git a/packages/ai/src/methods/chrome-adapter.test.ts b/packages/ai/src/methods/chrome-adapter.test.ts
diff --git a/packages/ai/src/models/generative-model.test.ts b/packages/ai/src/models/generative-model.test.ts
diff --git a/packages/ai/src/models/generative-model.ts b/packages/ai/src/models/generative-model.ts
diff --git a/packages/ai/src/types/chrome-adapter.ts b/packages/ai/src/types/chrome-adapter.ts
diff --git a/packages/ai/src/types/enums.ts b/packages/ai/src/types/enums.ts
diff --git a/packages/ai/src/types/language-model.ts b/packages/ai/src/types/language-model.ts
diff --git a/packages/ai/src/types/requests.ts b/packages/ai/src/types/requests.ts
