add top-level comments

Author: dlarocque

common/api-review/ai.api.md

@@ -104,7 +104,7 @@ export const BackendType: {
     readonly GOOGLE_AI: "GOOGLE_AI";
 };
 
-// @public (undocumented)
+// @public
 export type BackendType = (typeof BackendType)[keyof typeof BackendType];
 
 // @public
@@ -123,7 +123,7 @@ export const BlockReason: {
     readonly PROHIBITED_CONTENT: "PROHIBITED_CONTENT";
 };
 
-// @public (undocumented)
+// @public
 export type BlockReason = (typeof BlockReason)[keyof typeof BlockReason];
 
 // @public
@@ -342,7 +342,7 @@ export const FinishReason: {
     readonly MALFORMED_FUNCTION_CALL: "MALFORMED_FUNCTION_CALL";
 };
 
-// @public (undocumented)
+// @public
 export type FinishReason = (typeof FinishReason)[keyof typeof FinishReason];
 
 // @public
@@ -656,7 +656,7 @@ export const HarmBlockMethod: {
     readonly PROBABILITY: "PROBABILITY";
 };
 
-// @public (undocumented)
+// @public
 export type HarmBlockMethod = (typeof HarmBlockMethod)[keyof typeof HarmBlockMethod];
 
 // @public
@@ -668,7 +668,7 @@ export const HarmBlockThreshold: {
     readonly OFF: "OFF";
 };
 
-// @public (undocumented)
+// @public
 export type HarmBlockThreshold = (typeof HarmBlockThreshold)[keyof typeof HarmBlockThreshold];
 
 // @public
@@ -679,7 +679,7 @@ export const HarmCategory: {
     readonly HARM_CATEGORY_DANGEROUS_CONTENT: "HARM_CATEGORY_DANGEROUS_CONTENT";
 };
 
-// @public (undocumented)
+// @public
 export type HarmCategory = (typeof HarmCategory)[keyof typeof HarmCategory];
 
 // @public
@@ -690,7 +690,7 @@ export const HarmProbability: {
     readonly HIGH: "HIGH";
 };
 
-// @public (undocumented)
+// @public
 export type HarmProbability = (typeof HarmProbability)[keyof typeof HarmProbability];
 
 // @public
@@ -702,7 +702,7 @@ export const HarmSeverity: {
     readonly HARM_SEVERITY_UNSUPPORTED: "HARM_SEVERITY_UNSUPPORTED";
 };
 
-// @public (undocumented)
+// @public
 export type HarmSeverity = (typeof HarmSeverity)[keyof typeof HarmSeverity];
 
 // @beta
@@ -721,7 +721,7 @@ export const ImagenAspectRatio: {
     readonly PORTRAIT_9x16: "9:16";
 };
 
-// @public (undocumented)
+// @beta
 export type ImagenAspectRatio = (typeof ImagenAspectRatio)[keyof typeof ImagenAspectRatio];
 
 // @beta
@@ -785,7 +785,7 @@ export const ImagenPersonFilterLevel: {
     readonly ALLOW_ALL: "allow_all";
 };
 
-// @public (undocumented)
+// @beta
 export type ImagenPersonFilterLevel = (typeof ImagenPersonFilterLevel)[keyof typeof ImagenPersonFilterLevel];
 
 // @beta
@@ -796,7 +796,7 @@ export const ImagenSafetyFilterLevel: {
     readonly BLOCK_NONE: "block_none";
 };
 
-// @public (undocumented)
+// @beta
 export type ImagenSafetyFilterLevel = (typeof ImagenSafetyFilterLevel)[keyof typeof ImagenSafetyFilterLevel];
 
 // @beta
@@ -959,7 +959,7 @@ export const LiveResponseType: {
     TOOL_CALL_CANCELLATION: string;
 };
 
-// @public (undocumented)
+// @beta
 export type LiveResponseType = (typeof LiveResponseType)[keyof typeof LiveResponseType];
 
 // @beta
@@ -1009,7 +1009,7 @@ export const Modality: {
     readonly DOCUMENT: "DOCUMENT";
 };
 
-// @public (undocumented)
+// @public
 export type Modality = (typeof Modality)[keyof typeof Modality];
 
 // @public

docs-devsite/ai.md

@@ -176,25 +176,25 @@ The Firebase AI Web SDK.
 |  Type Alias | Description |
 |  --- | --- |
 |  [AIErrorCode](./ai.md#aierrorcode) | Standardized error codes that [AIError](./ai.aierror.md#aierror_class) can have. |
-|  [BackendType](./ai.md#backendtype) |  |
-|  [BlockReason](./ai.md#blockreason) |  |
-|  [FinishReason](./ai.md#finishreason) |  |
+|  [BackendType](./ai.md#backendtype) | An enum-like object containing constants that represent the supported backends for the Firebase AI SDK. |
+|  [BlockReason](./ai.md#blockreason) | Reason that a prompt was blocked. |
+|  [FinishReason](./ai.md#finishreason) | Reason that a candidate finished. |
 |  [FunctionCallingMode](./ai.md#functioncallingmode) |  |
-|  [HarmBlockMethod](./ai.md#harmblockmethod) |  |
-|  [HarmBlockThreshold](./ai.md#harmblockthreshold) |  |
-|  [HarmCategory](./ai.md#harmcategory) |  |
-|  [HarmProbability](./ai.md#harmprobability) |  |
-|  [HarmSeverity](./ai.md#harmseverity) |  |
-|  [ImagenAspectRatio](./ai.md#imagenaspectratio) |  |
-|  [ImagenPersonFilterLevel](./ai.md#imagenpersonfilterlevel) |  |
-|  [ImagenSafetyFilterLevel](./ai.md#imagensafetyfilterlevel) |  |
+|  [HarmBlockMethod](./ai.md#harmblockmethod) | This property is not supported in the Gemini Developer API ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class)<!-- -->). |
+|  [HarmBlockThreshold](./ai.md#harmblockthreshold) | Threshold above which a prompt or candidate will be blocked. |
+|  [HarmCategory](./ai.md#harmcategory) | Harm categories that would cause prompts or candidates to be blocked. |
+|  [HarmProbability](./ai.md#harmprobability) | Probability that a prompt or candidate matches a harm category. |
+|  [HarmSeverity](./ai.md#harmseverity) | Harm severity levels. |
+|  [ImagenAspectRatio](./ai.md#imagenaspectratio) | <b><i>(Public Preview)</i></b> Aspect ratios for Imagen images. |
+|  [ImagenPersonFilterLevel](./ai.md#imagenpersonfilterlevel) | <b><i>(Public Preview)</i></b> A filter level controlling whether generation of images containing people or faces is allowed. |
+|  [ImagenSafetyFilterLevel](./ai.md#imagensafetyfilterlevel) | <b><i>(Public Preview)</i></b> A filter level controlling how aggressively to filter sensitive content. |
 |  [InferenceMode](./ai.md#inferencemode) | <b><i>(Public Preview)</i></b> Determines whether inference happens on-device or in-cloud. |
 |  [Language](./ai.md#language) | <b><i>(Public Preview)</i></b> The programming language of the code. |
 |  [LanguageModelMessageContentValue](./ai.md#languagemodelmessagecontentvalue) | <b><i>(Public Preview)</i></b> Content formats that can be provided as on-device message content. |
 |  [LanguageModelMessageRole](./ai.md#languagemodelmessagerole) | <b><i>(Public Preview)</i></b> Allowable roles for on-device language model usage. |
 |  [LanguageModelMessageType](./ai.md#languagemodelmessagetype) | <b><i>(Public Preview)</i></b> Allowable types for on-device language model messages. |
-|  [LiveResponseType](./ai.md#liveresponsetype) |  |
-|  [Modality](./ai.md#modality) |  |
+|  [LiveResponseType](./ai.md#liveresponsetype) | <b><i>(Public Preview)</i></b> The types of responses that can be returned by [LiveSession.receive()](./ai.livesession.md#livesessionreceive)<!-- -->. |
+|  [Modality](./ai.md#modality) | Content part modality. |
 |  [Outcome](./ai.md#outcome) | <b><i>(Public Preview)</i></b> Represents the result of the code execution. |
 |  [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. |
@@ -821,6 +821,10 @@ export type AIErrorCode = (typeof AIErrorCode)[keyof typeof AIErrorCode];
 
 ## BackendType
 
+An enum-like object containing constants that represent the supported backends for the Firebase AI SDK.
+
+This determines which backend service (Vertex AI Gemini API or Gemini Developer API) the SDK will communicate with. These values are assigned to the `backendType` property within the specific backend configuration objects ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class) or [VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class)<!-- -->) to identify which service to target.
+
 <b>Signature:</b>
 
 ```typescript
@@ -829,6 +833,8 @@ export type BackendType = (typeof BackendType)[keyof typeof BackendType];
 
 ## BlockReason
 
+Reason that a prompt was blocked.
+
 <b>Signature:</b>
 
 ```typescript
@@ -837,6 +843,8 @@ export type BlockReason = (typeof BlockReason)[keyof typeof BlockReason];
 
 ## FinishReason
 
+Reason that a candidate finished.
+
 <b>Signature:</b>
 
 ```typescript
@@ -854,6 +862,8 @@ export type FunctionCallingMode = (typeof FunctionCallingMode)[keyof typeof Func
 
 ## HarmBlockMethod
 
+This property is not supported in the Gemini Developer API ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class)<!-- -->).
+
 <b>Signature:</b>
 
 ```typescript
@@ -862,6 +872,8 @@ export type HarmBlockMethod = (typeof HarmBlockMethod)[keyof typeof HarmBlockMet
 
 ## HarmBlockThreshold
 
+Threshold above which a prompt or candidate will be blocked.
+
 <b>Signature:</b>
 
 ```typescript
@@ -870,6 +882,8 @@ export type HarmBlockThreshold = (typeof HarmBlockThreshold)[keyof typeof HarmBl
 
 ## HarmCategory
 
+Harm categories that would cause prompts or candidates to be blocked.
+
 <b>Signature:</b>
 
 ```typescript
@@ -878,6 +892,8 @@ export type HarmCategory = (typeof HarmCategory)[keyof typeof HarmCategory];
 
 ## HarmProbability
 
+Probability that a prompt or candidate matches a harm category.
+
 <b>Signature:</b>
 
 ```typescript
@@ -886,6 +902,8 @@ export type HarmProbability = (typeof HarmProbability)[keyof typeof HarmProbabil
 
 ## HarmSeverity
 
+Harm severity levels.
+
 <b>Signature:</b>
 
 ```typescript
@@ -894,6 +912,13 @@ export type HarmSeverity = (typeof HarmSeverity)[keyof typeof HarmSeverity];
 
 ## ImagenAspectRatio
 
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Aspect ratios for Imagen images.
+
+To specify an aspect ratio for generated images, set the `aspectRatio` 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.
+
 <b>Signature:</b>
 
 ```typescript
@@ -902,6 +927,13 @@ export type ImagenAspectRatio = (typeof ImagenAspectRatio)[keyof typeof ImagenAs
 
 ## ImagenPersonFilterLevel
 
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+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.
+
 <b>Signature:</b>
 
 ```typescript
@@ -910,6 +942,13 @@ export type ImagenPersonFilterLevel = (typeof ImagenPersonFilterLevel)[keyof typ
 
 ## ImagenSafetyFilterLevel
 
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+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, `violence`<!-- -->, `sexual`<!-- -->, `derogatory`<!-- -->, and `toxic`<!-- -->). 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.
+
 <b>Signature:</b>
 
 ```typescript
@@ -983,6 +1022,11 @@ export type LanguageModelMessageType = 'text' | 'image' | 'audio';
 
 ## LiveResponseType
 
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+The types of responses that can be returned by [LiveSession.receive()](./ai.livesession.md#livesessionreceive)<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -991,6 +1035,8 @@ export type LiveResponseType = (typeof LiveResponseType)[keyof typeof LiveRespon
 
 ## Modality
 
+Content part modality.
+
 <b>Signature:</b>
 
 ```typescript

packages/ai/src/public-types.ts

@@ -73,6 +73,18 @@ export const BackendType = {
   GOOGLE_AI: 'GOOGLE_AI'
 } as const; // Using 'as const' makes the string values literal types
 
+/**
+ * An enum-like object containing constants that represent the supported backends
+ * for the Firebase AI SDK.
+ *
+ * @remarks
+ * This determines which backend service (Vertex AI Gemini API or Gemini Developer API)
+ * the SDK will communicate with. These values are assigned to the `backendType` property
+ * within the specific backend configuration objects ({@link GoogleAIBackend} or
+ * {@link VertexAIBackend}) to identify which service to target.
+ *
+ * @public
+ */
 export type BackendType = (typeof BackendType)[keyof typeof BackendType];
 
 /**