From a6c0c32f80d04fc660c932edee5f5523a3f6dc87 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Tue, 23 Sep 2025 12:38:53 -0400 Subject: [PATCH 1/3] docs(ai): Document enum values in top-level JSDoc comments --- common/api-review/ai.api.md | 24 +- docs-devsite/ai.md | 110 ++++----- packages/ai/src/public-types.ts | 31 +-- packages/ai/src/types/enums.ts | 300 ++++++++++------------- packages/ai/src/types/imagen/requests.ts | 117 +++------ packages/ai/src/types/responses.ts | 14 +- 6 files changed, 244 insertions(+), 352 deletions(-) diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md index d4c3c1ad507..f1bd025a724 100644 --- a/common/api-review/ai.api.md +++ b/common/api-review/ai.api.md @@ -104,7 +104,7 @@ export const BackendType: { readonly GOOGLE_AI: "GOOGLE_AI"; }; -// @public +// @public (undocumented) export type BackendType = (typeof BackendType)[keyof typeof BackendType]; // @public @@ -123,7 +123,7 @@ export const BlockReason: { readonly PROHIBITED_CONTENT: "PROHIBITED_CONTENT"; }; -// @public +// @public (undocumented) export type BlockReason = (typeof BlockReason)[keyof typeof BlockReason]; // @public @@ -342,7 +342,7 @@ export const FinishReason: { readonly MALFORMED_FUNCTION_CALL: "MALFORMED_FUNCTION_CALL"; }; -// @public +// @public (undocumented) export type FinishReason = (typeof FinishReason)[keyof typeof FinishReason]; // @public @@ -650,7 +650,7 @@ export const HarmBlockMethod: { readonly PROBABILITY: "PROBABILITY"; }; -// @public +// @public (undocumented) export type HarmBlockMethod = (typeof HarmBlockMethod)[keyof typeof HarmBlockMethod]; // @public @@ -662,7 +662,7 @@ export const HarmBlockThreshold: { readonly OFF: "OFF"; }; -// @public +// @public (undocumented) export type HarmBlockThreshold = (typeof HarmBlockThreshold)[keyof typeof HarmBlockThreshold]; // @public @@ -673,7 +673,7 @@ export const HarmCategory: { readonly HARM_CATEGORY_DANGEROUS_CONTENT: "HARM_CATEGORY_DANGEROUS_CONTENT"; }; -// @public +// @public (undocumented) export type HarmCategory = (typeof HarmCategory)[keyof typeof HarmCategory]; // @public @@ -684,7 +684,7 @@ export const HarmProbability: { readonly HIGH: "HIGH"; }; -// @public +// @public (undocumented) export type HarmProbability = (typeof HarmProbability)[keyof typeof HarmProbability]; // @public @@ -696,7 +696,7 @@ export const HarmSeverity: { readonly HARM_SEVERITY_UNSUPPORTED: "HARM_SEVERITY_UNSUPPORTED"; }; -// @public +// @public (undocumented) export type HarmSeverity = (typeof HarmSeverity)[keyof typeof HarmSeverity]; // @beta @@ -715,7 +715,7 @@ export const ImagenAspectRatio: { readonly PORTRAIT_9x16: "9:16"; }; -// @beta +// @public (undocumented) export type ImagenAspectRatio = (typeof ImagenAspectRatio)[keyof typeof ImagenAspectRatio]; // @beta @@ -779,7 +779,7 @@ export const ImagenPersonFilterLevel: { readonly ALLOW_ALL: "allow_all"; }; -// @beta +// @public (undocumented) export type ImagenPersonFilterLevel = (typeof ImagenPersonFilterLevel)[keyof typeof ImagenPersonFilterLevel]; // @beta @@ -790,7 +790,7 @@ export const ImagenSafetyFilterLevel: { readonly BLOCK_NONE: "block_none"; }; -// @beta +// @public (undocumented) export type ImagenSafetyFilterLevel = (typeof ImagenSafetyFilterLevel)[keyof typeof ImagenSafetyFilterLevel]; // @beta @@ -1002,7 +1002,7 @@ export const Modality: { readonly DOCUMENT: "DOCUMENT"; }; -// @public +// @public (undocumented) export type Modality = (typeof Modality)[keyof typeof Modality]; // @public diff --git a/docs-devsite/ai.md b/docs-devsite/ai.md index 78d82d23800..0178c01a10d 100644 --- a/docs-devsite/ai.md +++ b/docs-devsite/ai.md @@ -145,7 +145,7 @@ The Firebase AI Web SDK. | Variable | Description | | --- | --- | | [AIErrorCode](./ai.md#aierrorcode) | Standardized error codes that [AIError](./ai.aierror.md#aierror_class) can have. | -| [BackendType](./ai.md#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. | +| [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) | | @@ -154,9 +154,9 @@ The Firebase AI Web SDK. | [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) | (Public Preview) 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. | -| [ImagenPersonFilterLevel](./ai.md#imagenpersonfilterlevel) | (Public Preview) A filter level controlling whether generation of images containing people or faces is allowed.See the personGeneration documentation for more details. | -| [ImagenSafetyFilterLevel](./ai.md#imagensafetyfilterlevel) | (Public Preview) 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. | +| [ImagenAspectRatio](./ai.md#imagenaspectratio) | (Public Preview) Aspect ratios for Imagen images. | +| [ImagenPersonFilterLevel](./ai.md#imagenpersonfilterlevel) | (Public Preview) A filter level controlling whether generation of images containing people or faces is allowed. | +| [ImagenSafetyFilterLevel](./ai.md#imagensafetyfilterlevel) | (Public Preview) A filter level controlling how aggressively to filter sensitive content. | | [InferenceMode](./ai.md#inferencemode) | (Public Preview) Determines whether inference happens on-device or in-cloud. | | [Language](./ai.md#language) | The programming language of the code. | | [LiveResponseType](./ai.md#liveresponsetype) | (Public Preview) The types of responses that can be returned by [LiveSession.receive()](./ai.livesession.md#livesessionreceive). | @@ -171,25 +171,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) | Type alias representing valid backend types. It can be either 'VERTEX_AI' or 'GOOGLE_AI'. | -| [BlockReason](./ai.md#blockreason) | Reason that a prompt was blocked. | -| [FinishReason](./ai.md#finishreason) | Reason that a candidate finished. | +| [BackendType](./ai.md#backendtype) | | +| [BlockReason](./ai.md#blockreason) | | +| [FinishReason](./ai.md#finishreason) | | | [FunctionCallingMode](./ai.md#functioncallingmode) | | -| [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) | (Public Preview) 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. | -| [ImagenPersonFilterLevel](./ai.md#imagenpersonfilterlevel) | (Public Preview) A filter level controlling whether generation of images containing people or faces is allowed.See the personGeneration documentation for more details. | -| [ImagenSafetyFilterLevel](./ai.md#imagensafetyfilterlevel) | (Public Preview) 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. | +| [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) | | | [InferenceMode](./ai.md#inferencemode) | (Public Preview) Determines whether inference happens on-device or in-cloud. | | [Language](./ai.md#language) | The programming language of the code. | | [LanguageModelMessageContentValue](./ai.md#languagemodelmessagecontentvalue) | (Public Preview) Content formats that can be provided as on-device message content. | | [LanguageModelMessageRole](./ai.md#languagemodelmessagerole) | (Public Preview) Allowable roles for on-device language model usage. | | [LanguageModelMessageType](./ai.md#languagemodelmessagetype) | (Public Preview) Allowable types for on-device language model messages. | | [LiveResponseType](./ai.md#liveresponsetype) | (Public Preview) The types of responses that can be returned by [LiveSession.receive()](./ai.livesession.md#livesessionreceive). This is a property on all messages that can be used for type narrowing. This property is not returned by the server, it is assigned to a server message object once it's parsed. | -| [Modality](./ai.md#modality) | Content part modality. | +| [Modality](./ai.md#modality) | | | [Outcome](./ai.md#outcome) | 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) | (Public Preview) Generation modalities to be returned in generation responses. | @@ -431,9 +431,9 @@ 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. +An enum-like object containing constants that represent the supported backends for the Firebase AI SDK. -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. +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.
VERTEX\_AI: Identifies the backend service for the Vertex AI Gemini API provided through Google Cloud. Use this constant when creating a [VertexAIBackend](./ai.vertexaibackend.md#vertexaibackend_class) configuration.
GOOGLE\_AI: Identifies the backend service for the Gemini Developer API ([Google AI](https://ai.google/)). Use this constant when creating a [GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class) configuration. Signature: @@ -448,6 +448,8 @@ BackendType: { Reason that a prompt was blocked. +SAFETY: Content was blocked by safety settings.
OTHER: Content was blocked, but the reason is uncategorized.
BLOCKLIST: Content was blocked because it contained terms from the terminology blocklist.
PROHIBITED\_CONTENT: Content was blocked due to prohibited content. + Signature: ```typescript @@ -463,6 +465,8 @@ BlockReason: { Reason that a candidate finished. +STOP: Natural stop point of the model or provided stop sequence.
MAX\_TOKENS: The maximum number of tokens as specified in the request was reached.
SAFETY: The candidate content was flagged for safety reasons.
RECITATION: The candidate content was flagged for recitation reasons.
OTHER: Unknown reason.
BLOCKLIST: The candidate content contained forbidden terms.
PROHIBITED\_CONTENT: The candidate content potentially contained prohibited content.
SPII: The candidate content potentially contained Sensitive Personally Identifiable Information (SPII).
MALFORMED\_FUNCTION\_CALL: The function call generated by the model was invalid. + Signature: ```typescript @@ -481,6 +485,7 @@ FinishReason: { ## FunctionCallingMode +- AUTO: Default model behavior; model decides to predict either a function call or a natural language response. - ANY: Model is constrained to always predicting a function call only. If `allowed_function_names` is set, the predicted function call will be limited to any one of `allowed_function_names`, else the predicted function call will be any one of the provided `function_declarations`.
NONE: Model will not predict any function call. Model behavior is same as when not passing any function declarations. Signature: @@ -496,6 +501,8 @@ FunctionCallingMode: { This property is not supported in the Gemini Developer API ([GoogleAIBackend](./ai.googleaibackend.md#googleaibackend_class)). +SEVERITY: The harm block method uses both probability and severity scores.
PROBABILITY: The harm block method uses the probability score. + Signature: ```typescript @@ -509,6 +516,8 @@ HarmBlockMethod: { Threshold above which a prompt or candidate will be blocked. +BLOCK\_LOW\_AND\_ABOVE: Content with `NEGLIGIBLE` will be allowed.
BLOCK\_MEDIUM\_AND\_ABOVE: Content with `NEGLIGIBLE` and `LOW` will be allowed.
BLOCK\_ONLY\_HIGH: Content with `NEGLIGIBLE`, `LOW`, and `MEDIUM` will be allowed.
BLOCK\_NONE: All content will be allowed.
OFF: All content will be allowed. This is the same as `BLOCK_NONE`, but the metadata corresponding to the `HarmCategory` will not be present in the response. + Signature: ```typescript @@ -525,6 +534,8 @@ HarmBlockThreshold: { Harm categories that would cause prompts or candidates to be blocked. +HARM\_CATEGORY\_HATE\_SPEECH: Category for hate speech.
HARM\_CATEGORY\_SEXUALLY\_EXPLICIT: Category for sexually explicit content.
HARM\_CATEGORY\_HARASSMENT: Category for harassment.
HARM\_CATEGORY\_DANGEROUS\_CONTENT: Category for dangerous content. + Signature: ```typescript @@ -540,6 +551,8 @@ HarmCategory: { Probability that a prompt or candidate matches a harm category. +NEGLIGIBLE: Content has a negligible chance of being unsafe.
LOW: Content has a low chance of being unsafe.
MEDIUM: Content has a medium chance of being unsafe.
HIGH: Content has a high chance of being unsafe. + Signature: ```typescript @@ -555,6 +568,8 @@ HarmProbability: { Harm severity levels. +HARM\_SEVERITY\_NEGLIGIBLE: Negligible level of harm severity.
HARM\_SEVERITY\_LOW: Low level of harm severity.
HARM\_SEVERITY\_MEDIUM: Medium level of harm severity.
HARM\_SEVERITY\_HIGH: High level of harm severity.
HARM\_SEVERITY\_UNSUPPORTED: Harm severity is not supported. The GoogleAI backend does not support `HarmSeverity`, so this value is used as a fallback. + Signature: ```typescript @@ -574,9 +589,7 @@ HarmSeverity: { 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. +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.
SQUARE: Square (1:1) aspect ratio.
LANDSCAPE\_3x4: Landscape (3:4) aspect ratio.
PORTRAIT\_4x3: Portrait (4:3) aspect ratio.
LANDSCAPE\_16x9: Landscape (16:9) aspect ratio.
PORTRAIT\_9x16: Portrait (9:16) aspect ratio. Signature: @@ -597,7 +610,7 @@ ImagenAspectRatio: { A filter level controlling whether generation of images containing people or faces is allowed. -See the personGeneration documentation for more details. +See the personGeneration documentation for more details.
BLOCK\_ALL: Disallow generation of images containing people or faces; images of people are filtered out.
ALLOW\_ADULT: Allow generation of images containing adults only; images of children are filtered out. Generation of images containing people or faces may require your use case to be reviewed and approved by Cloud support; see the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen) for more details.
ALLOW\_ALL: Allow generation of images containing adults only; images of children are filtered out. Generation of images containing people or faces may require your use case to be reviewed and approved by Cloud support; see the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen) for more details. Signature: @@ -616,7 +629,7 @@ ImagenPersonFilterLevel: { 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. +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.
BLOCK\_LOW\_AND\_ABOVE: The most aggressive filtering level; most strict blocking.
BLOCK\_MEDIUM\_AND\_ABOVE: Blocks some sensitive prompts and responses.
BLOCK\_ONLY\_HIGH: Blocks few sensitive prompts and responses.
BLOCK\_NONE: 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. Signature: @@ -669,6 +682,8 @@ Language: { The types of responses that can be returned by [LiveSession.receive()](./ai.livesession.md#livesessionreceive). +SERVER\_CONTENT: An incremental content update from the model.
TOOL\_CALL: A request from the model for the client to execute one or more functions.
TOOL\_CALL\_CANCELLATION: Notification to cancel a previous function call triggered by [LiveServerToolCall](./ai.liveservertoolcall.md#liveservertoolcall_interface). + Signature: ```typescript @@ -683,6 +698,8 @@ LiveResponseType: { Content part modality. +MODALITY\_UNSPECIFIED: Unspecified modality.
TEXT: Plain text.
IMAGE: Image.
VIDEO: Video.
AUDIO: Audio.
DOCUMENT: Document (for example, PDF). + Signature: ```typescript @@ -715,6 +732,8 @@ Outcome: { Possible roles. +user: The user is the one making the request.
model: The model is the one generating the response.
function: The role for a response from a function call.
system: The role for a system instruction. + Signature: ```typescript @@ -728,6 +747,8 @@ POSSIBLE_ROLES: readonly ["user", "model", "function", "system"] Generation modalities to be returned in generation responses. +TEXT: Text.
IMAGE: Image.
AUDIO: Audio. + Signature: ```typescript @@ -767,8 +788,6 @@ export type AIErrorCode = (typeof AIErrorCode)[keyof typeof AIErrorCode]; ## BackendType -Type alias representing valid backend types. It can be either `'VERTEX_AI'` or `'GOOGLE_AI'`. - Signature: ```typescript @@ -777,8 +796,6 @@ export type BackendType = (typeof BackendType)[keyof typeof BackendType]; ## BlockReason -Reason that a prompt was blocked. - Signature: ```typescript @@ -787,8 +804,6 @@ export type BlockReason = (typeof BlockReason)[keyof typeof BlockReason]; ## FinishReason -Reason that a candidate finished. - Signature: ```typescript @@ -806,8 +821,6 @@ 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)). - Signature: ```typescript @@ -816,8 +829,6 @@ export type HarmBlockMethod = (typeof HarmBlockMethod)[keyof typeof HarmBlockMet ## HarmBlockThreshold -Threshold above which a prompt or candidate will be blocked. - Signature: ```typescript @@ -826,8 +837,6 @@ export type HarmBlockThreshold = (typeof HarmBlockThreshold)[keyof typeof HarmBl ## HarmCategory -Harm categories that would cause prompts or candidates to be blocked. - Signature: ```typescript @@ -836,8 +845,6 @@ export type HarmCategory = (typeof HarmCategory)[keyof typeof HarmCategory]; ## HarmProbability -Probability that a prompt or candidate matches a harm category. - Signature: ```typescript @@ -846,8 +853,6 @@ export type HarmProbability = (typeof HarmProbability)[keyof typeof HarmProbabil ## HarmSeverity -Harm severity levels. - Signature: ```typescript @@ -856,15 +861,6 @@ 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. - Signature: ```typescript @@ -873,13 +869,6 @@ 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 personGeneration documentation for more details. - Signature: ```typescript @@ -888,13 +877,6 @@ 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. - Signature: ```typescript @@ -978,8 +960,6 @@ export type LiveResponseType = (typeof LiveResponseType)[keyof typeof LiveRespon ## Modality -Content part modality. - Signature: ```typescript @@ -1023,6 +1003,8 @@ export type ResponseModality = (typeof ResponseModality)[keyof typeof ResponseMo Role is the producer of the content. +user: The user is the one making the request.
model: The model is the one generating the response.
function: The role for a response from a function call.
system: The role for a system instruction. + Signature: ```typescript diff --git a/packages/ai/src/public-types.ts b/packages/ai/src/public-types.ts index fff41251a01..ec756c5992a 100644 --- a/packages/ai/src/public-types.ts +++ b/packages/ai/src/public-types.ts @@ -53,35 +53,26 @@ export interface AI { /** * 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 ({@link GoogleAIBackend} or {@link VertexAIBackend}) to identify - * which service to target. + * @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. + *
+ * VERTEX_AI: Identifies the backend service for the Vertex AI Gemini API provided through Google Cloud. + * Use this constant when creating a {@link VertexAIBackend} configuration. + *
+ * GOOGLE_AI: Identifies the backend service for the Gemini Developer API ({@link https://ai.google/ | Google AI}). + * Use this constant when creating a {@link GoogleAIBackend} configuration. * * @public */ export const BackendType = { - /** - * Identifies the backend service for the Vertex AI Gemini API provided through Google Cloud. - * Use this constant when creating a {@link VertexAIBackend} configuration. - */ VERTEX_AI: 'VERTEX_AI', - - /** - * Identifies the backend service for the Gemini Developer API ({@link https://ai.google/ | Google AI}). - * Use this constant when creating a {@link GoogleAIBackend} configuration. - */ GOOGLE_AI: 'GOOGLE_AI' } as const; // Using 'as const' makes the string values literal types -/** - * Type alias representing valid backend types. - * It can be either `'VERTEX_AI'` or `'GOOGLE_AI'`. - * - * @public - */ export type BackendType = (typeof BackendType)[keyof typeof BackendType]; /** diff --git a/packages/ai/src/types/enums.ts b/packages/ai/src/types/enums.ts index 997df1265b0..9b5a9d26a98 100644 --- a/packages/ai/src/types/enums.ts +++ b/packages/ai/src/types/enums.ts @@ -17,18 +17,48 @@ /** * Role is the producer of the content. + * + * @remarks + * user: The user is the one making the request. + *
+ * model: The model is the one generating the response. + *
+ * function: The role for a response from a function call. + *
+ * system: The role for a system instruction. + * * @public */ export type Role = (typeof POSSIBLE_ROLES)[number]; /** * Possible roles. + * + * @remarks + * user: The user is the one making the request. + *
+ * model: The model is the one generating the response. + *
+ * function: The role for a response from a function call. + *
+ * system: The role for a system instruction. + * * @public */ export const POSSIBLE_ROLES = ['user', 'model', 'function', 'system'] as const; /** * Harm categories that would cause prompts or candidates to be blocked. + * + * @remarks + * HARM_CATEGORY_HATE_SPEECH: Category for hate speech. + *
+ * HARM_CATEGORY_SEXUALLY_EXPLICIT: Category for sexually explicit content. + *
+ * HARM_CATEGORY_HARASSMENT: Category for harassment. + *
+ * HARM_CATEGORY_DANGEROUS_CONTENT: Category for dangerous content. + * * @public */ export const HarmCategory = { @@ -38,235 +68,182 @@ export const HarmCategory = { HARM_CATEGORY_DANGEROUS_CONTENT: 'HARM_CATEGORY_DANGEROUS_CONTENT' } as const; -/** - * Harm categories that would cause prompts or candidates to be blocked. - * @public - */ export type HarmCategory = (typeof HarmCategory)[keyof typeof HarmCategory]; /** * Threshold above which a prompt or candidate will be blocked. + * + * @remarks + * BLOCK_LOW_AND_ABOVE: Content with `NEGLIGIBLE` will be allowed. + *
+ * BLOCK_MEDIUM_AND_ABOVE: Content with `NEGLIGIBLE` and `LOW` will be allowed. + *
+ * BLOCK_ONLY_HIGH: Content with `NEGLIGIBLE`, `LOW`, and `MEDIUM` will be allowed. + *
+ * BLOCK_NONE: All content will be allowed. + *
+ * OFF: All content will be allowed. This is the same as `BLOCK_NONE`, but the metadata corresponding + * to the `HarmCategory` will not be present in the response. + * * @public */ export const HarmBlockThreshold = { - /** - * Content with `NEGLIGIBLE` will be allowed. - */ BLOCK_LOW_AND_ABOVE: 'BLOCK_LOW_AND_ABOVE', - /** - * Content with `NEGLIGIBLE` and `LOW` will be allowed. - */ BLOCK_MEDIUM_AND_ABOVE: 'BLOCK_MEDIUM_AND_ABOVE', - /** - * Content with `NEGLIGIBLE`, `LOW`, and `MEDIUM` will be allowed. - */ BLOCK_ONLY_HIGH: 'BLOCK_ONLY_HIGH', - /** - * All content will be allowed. - */ BLOCK_NONE: 'BLOCK_NONE', - /** - * All content will be allowed. This is the same as `BLOCK_NONE`, but the metadata corresponding - * to the {@link (HarmCategory:type)} will not be present in the response. - */ OFF: 'OFF' } as const; -/** - * Threshold above which a prompt or candidate will be blocked. - * @public - */ export type HarmBlockThreshold = (typeof HarmBlockThreshold)[keyof typeof HarmBlockThreshold]; /** * This property is not supported in the Gemini Developer API ({@link GoogleAIBackend}). * + * @remarks + * SEVERITY: The harm block method uses both probability and severity scores. + *
+ * PROBABILITY: The harm block method uses the probability score. + * * @public */ export const HarmBlockMethod = { - /** - * The harm block method uses both probability and severity scores. - */ SEVERITY: 'SEVERITY', - /** - * The harm block method uses the probability score. - */ PROBABILITY: 'PROBABILITY' } as const; -/** - * This property is not supported in the Gemini Developer API ({@link GoogleAIBackend}). - * - * @public - */ export type HarmBlockMethod = (typeof HarmBlockMethod)[keyof typeof HarmBlockMethod]; /** * Probability that a prompt or candidate matches a harm category. + * + * @remarks + * NEGLIGIBLE: Content has a negligible chance of being unsafe. + *
+ * LOW: Content has a low chance of being unsafe. + *
+ * MEDIUM: Content has a medium chance of being unsafe. + *
+ * HIGH: Content has a high chance of being unsafe. + * * @public */ export const HarmProbability = { - /** - * Content has a negligible chance of being unsafe. - */ NEGLIGIBLE: 'NEGLIGIBLE', - /** - * Content has a low chance of being unsafe. - */ LOW: 'LOW', - /** - * Content has a medium chance of being unsafe. - */ MEDIUM: 'MEDIUM', - /** - * Content has a high chance of being unsafe. - */ HIGH: 'HIGH' } as const; -/** - * Probability that a prompt or candidate matches a harm category. - * @public - */ export type HarmProbability = (typeof HarmProbability)[keyof typeof HarmProbability]; /** * Harm severity levels. + * + * @remarks + * HARM_SEVERITY_NEGLIGIBLE: Negligible level of harm severity. + *
+ * HARM_SEVERITY_LOW: Low level of harm severity. + *
+ * HARM_SEVERITY_MEDIUM: Medium level of harm severity. + *
+ * HARM_SEVERITY_HIGH: High level of harm severity. + *
+ * HARM_SEVERITY_UNSUPPORTED: Harm severity is not supported. The GoogleAI backend does not support `HarmSeverity`, so this value is used as a fallback. + * * @public */ export const HarmSeverity = { - /** - * Negligible level of harm severity. - */ HARM_SEVERITY_NEGLIGIBLE: 'HARM_SEVERITY_NEGLIGIBLE', - /** - * Low level of harm severity. - */ HARM_SEVERITY_LOW: 'HARM_SEVERITY_LOW', - /** - * Medium level of harm severity. - */ HARM_SEVERITY_MEDIUM: 'HARM_SEVERITY_MEDIUM', - /** - * High level of harm severity. - */ HARM_SEVERITY_HIGH: 'HARM_SEVERITY_HIGH', - /** - * Harm severity is not supported. - * - * @remarks - * The GoogleAI backend does not support `HarmSeverity`, so this value is used as a fallback. - */ HARM_SEVERITY_UNSUPPORTED: 'HARM_SEVERITY_UNSUPPORTED' } as const; -/** - * Harm severity levels. - * @public - */ export type HarmSeverity = (typeof HarmSeverity)[keyof typeof HarmSeverity]; /** * Reason that a prompt was blocked. + * + * @remarks + * SAFETY: Content was blocked by safety settings. + *
+ * OTHER: Content was blocked, but the reason is uncategorized. + *
+ * BLOCKLIST: Content was blocked because it contained terms from the terminology blocklist. + *
+ * PROHIBITED_CONTENT: Content was blocked due to prohibited content. + * * @public */ export const BlockReason = { - /** - * Content was blocked by safety settings. - */ SAFETY: 'SAFETY', - /** - * Content was blocked, but the reason is uncategorized. - */ OTHER: 'OTHER', - /** - * Content was blocked because it contained terms from the terminology blocklist. - */ BLOCKLIST: 'BLOCKLIST', - /** - * Content was blocked due to prohibited content. - */ PROHIBITED_CONTENT: 'PROHIBITED_CONTENT' } as const; -/** - * Reason that a prompt was blocked. - * @public - */ export type BlockReason = (typeof BlockReason)[keyof typeof BlockReason]; /** * Reason that a candidate finished. + * + * @remarks + * STOP: Natural stop point of the model or provided stop sequence. + *
+ * MAX_TOKENS: The maximum number of tokens as specified in the request was reached. + *
+ * SAFETY: The candidate content was flagged for safety reasons. + *
+ * RECITATION: The candidate content was flagged for recitation reasons. + *
+ * OTHER: Unknown reason. + *
+ * BLOCKLIST: The candidate content contained forbidden terms. + *
+ * PROHIBITED_CONTENT: The candidate content potentially contained prohibited content. + *
+ * SPII: The candidate content potentially contained Sensitive Personally Identifiable Information (SPII). + *
+ * MALFORMED_FUNCTION_CALL: The function call generated by the model was invalid. + * * @public */ export const FinishReason = { - /** - * Natural stop point of the model or provided stop sequence. - */ STOP: 'STOP', - /** - * The maximum number of tokens as specified in the request was reached. - */ MAX_TOKENS: 'MAX_TOKENS', - /** - * The candidate content was flagged for safety reasons. - */ SAFETY: 'SAFETY', - /** - * The candidate content was flagged for recitation reasons. - */ RECITATION: 'RECITATION', - /** - * Unknown reason. - */ OTHER: 'OTHER', - /** - * The candidate content contained forbidden terms. - */ BLOCKLIST: 'BLOCKLIST', - /** - * The candidate content potentially contained prohibited content. - */ PROHIBITED_CONTENT: 'PROHIBITED_CONTENT', - /** - * The candidate content potentially contained Sensitive Personally Identifiable Information (SPII). - */ SPII: 'SPII', - /** - * The function call generated by the model was invalid. - */ MALFORMED_FUNCTION_CALL: 'MALFORMED_FUNCTION_CALL' } as const; -/** - * Reason that a candidate finished. - * @public - */ export type FinishReason = (typeof FinishReason)[keyof typeof FinishReason]; /** + * @remarks + * - AUTO: Default model behavior; model decides to predict either a function call + * or a natural language response. + * - ANY: Model is constrained to always predicting a function call only. + * If `allowed_function_names` is set, the predicted function call will be + * limited to any one of `allowed_function_names`, else the predicted + * function call will be any one of the provided `function_declarations`. + *
+ * NONE: Model will not predict any function call. Model behavior is same as when + * not passing any function declarations. + * * @public */ export const FunctionCallingMode = { - /** - * Default model behavior; model decides to predict either a function call - * or a natural language response. - */ AUTO: 'AUTO', - /** - * Model is constrained to always predicting a function call only. - * If `allowed_function_names` is set, the predicted function call will be - * limited to any one of `allowed_function_names`, else the predicted - * function call will be any one of the provided `function_declarations`. - */ ANY: 'ANY', - /** - * Model will not predict any function call. Model behavior is same as when - * not passing any function declarations. - */ NONE: 'NONE' } as const; @@ -278,61 +255,48 @@ export type FunctionCallingMode = /** * Content part modality. + * + * @remarks + * MODALITY_UNSPECIFIED: Unspecified modality. + *
+ * TEXT: Plain text. + *
+ * IMAGE: Image. + *
+ * VIDEO: Video. + *
+ * AUDIO: Audio. + *
+ * DOCUMENT: Document (for example, PDF). + * * @public */ export const Modality = { - /** - * Unspecified modality. - */ MODALITY_UNSPECIFIED: 'MODALITY_UNSPECIFIED', - /** - * Plain text. - */ TEXT: 'TEXT', - /** - * Image. - */ IMAGE: 'IMAGE', - /** - * Video. - */ VIDEO: 'VIDEO', - /** - * Audio. - */ AUDIO: 'AUDIO', - /** - * Document (for example, PDF). - */ DOCUMENT: 'DOCUMENT' } as const; -/** - * Content part modality. - * @public - */ export type Modality = (typeof Modality)[keyof typeof Modality]; /** * Generation modalities to be returned in generation responses. * + * @remarks + * TEXT: Text. + *
+ * IMAGE: Image. + *
+ * AUDIO: Audio. + * * @beta */ export const ResponseModality = { - /** - * Text. - * @beta - */ TEXT: 'TEXT', - /** - * Image. - * @beta - */ IMAGE: 'IMAGE', - /** - * Audio. - * @beta - */ AUDIO: 'AUDIO' } as const; diff --git a/packages/ai/src/types/imagen/requests.ts b/packages/ai/src/types/imagen/requests.ts index 47d1afe3b01..216b91c77ae 100644 --- a/packages/ai/src/types/imagen/requests.ts +++ b/packages/ai/src/types/imagen/requests.ts @@ -101,91 +101,63 @@ export interface ImagenGenerationConfig { /** * A filter level controlling how aggressively to filter sensitive content. * + * @remarks * 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 {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } * and the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters | Responsible AI and usage guidelines} * for more details. + *
+ * BLOCK_LOW_AND_ABOVE: The most aggressive filtering level; most strict blocking. + *
+ * BLOCK_MEDIUM_AND_ABOVE: Blocks some sensitive prompts and responses. + *
+ * BLOCK_ONLY_HIGH: Blocks few sensitive prompts and responses. + *
+ * BLOCK_NONE: 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. * * @beta */ export const ImagenSafetyFilterLevel = { - /** - * The most aggressive filtering level; most strict blocking. - */ BLOCK_LOW_AND_ABOVE: 'block_low_and_above', - /** - * Blocks some sensitive prompts and responses. - */ BLOCK_MEDIUM_AND_ABOVE: 'block_medium_and_above', - /** - * Blocks few sensitive prompts and responses. - */ BLOCK_ONLY_HIGH: 'block_only_high', - /** - * 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_NONE: 'block_none' } as const; -/** - * 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 {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } - * and the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters | Responsible AI and usage guidelines} - * for more details. - * - * @beta - */ export type ImagenSafetyFilterLevel = (typeof ImagenSafetyFilterLevel)[keyof typeof ImagenSafetyFilterLevel]; /** * A filter level controlling whether generation of images containing people or faces is allowed. * + * @remarks * See the personGeneration * documentation for more details. + *
+ * BLOCK_ALL: Disallow generation of images containing people or faces; images of people are filtered out. + *
+ * ALLOW_ADULT: Allow generation of images containing adults only; images of children are filtered out. + * Generation of images containing people or faces may require your use case to be + * reviewed and approved by Cloud support; see the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen | Responsible AI and usage guidelines} + * for more details. + *
+ * ALLOW_ALL: Allow generation of images containing adults only; images of children are filtered out. + * Generation of images containing people or faces may require your use case to be + * reviewed and approved by Cloud support; see the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen | Responsible AI and usage guidelines} + * for more details. * * @beta */ export const ImagenPersonFilterLevel = { - /** - * Disallow generation of images containing people or faces; images of people are filtered out. - */ BLOCK_ALL: 'dont_allow', - /** - * Allow generation of images containing adults only; images of children are filtered out. - * - * Generation of images containing people or faces may require your use case to be - * reviewed and approved by Cloud support; see the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen | Responsible AI and usage guidelines} - * for more details. - */ ALLOW_ADULT: 'allow_adult', - /** - * Allow generation of images containing adults only; images of children are filtered out. - * - * Generation of images containing people or faces may require your use case to be - * reviewed and approved by Cloud support; see the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen | Responsible AI and usage guidelines} - * for more details. - */ ALLOW_ALL: 'allow_all' } as const; -/** - * A filter level controlling whether generation of images containing people or faces is allowed. - * - * See the personGeneration - * documentation for more details. - * - * @beta - */ export type ImagenPersonFilterLevel = (typeof ImagenPersonFilterLevel)[keyof typeof ImagenPersonFilterLevel]; @@ -212,47 +184,30 @@ export interface ImagenSafetySettings { /** * Aspect ratios for Imagen images. * + * @remarks * To specify an aspect ratio for generated images, set the `aspectRatio` property in your - * {@link ImagenGenerationConfig}. - * - * See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } + * {@link ImagenGenerationConfig}. See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } * for more details and examples of the supported aspect ratios. + *
+ * SQUARE: Square (1:1) aspect ratio. + *
+ * LANDSCAPE_3x4: Landscape (3:4) aspect ratio. + *
+ * PORTRAIT_4x3: Portrait (4:3) aspect ratio. + *
+ * LANDSCAPE_16x9: Landscape (16:9) aspect ratio. + *
+ * PORTRAIT_9x16: Portrait (9:16) aspect ratio. * * @beta */ export const ImagenAspectRatio = { - /** - * Square (1:1) aspect ratio. - */ 'SQUARE': '1:1', - /** - * Landscape (3:4) aspect ratio. - */ 'LANDSCAPE_3x4': '3:4', - /** - * Portrait (4:3) aspect ratio. - */ 'PORTRAIT_4x3': '4:3', - /** - * Landscape (16:9) aspect ratio. - */ 'LANDSCAPE_16x9': '16:9', - /** - * Portrait (9:16) aspect ratio. - */ 'PORTRAIT_9x16': '9:16' } as const; -/** - * Aspect ratios for Imagen images. - * - * To specify an aspect ratio for generated images, set the `aspectRatio` property in your - * {@link ImagenGenerationConfig}. - * - * See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } - * for more details and examples of the supported aspect ratios. - * - * @beta - */ export type ImagenAspectRatio = (typeof ImagenAspectRatio)[keyof typeof ImagenAspectRatio]; diff --git a/packages/ai/src/types/responses.ts b/packages/ai/src/types/responses.ts index 4a01e79a77c..ce1838c6283 100644 --- a/packages/ai/src/types/responses.ts +++ b/packages/ai/src/types/responses.ts @@ -480,6 +480,13 @@ export interface LiveServerToolCallCancellation { /** * The types of responses that can be returned by {@link LiveSession.receive}. * + * @remarks + * SERVER_CONTENT: An incremental content update from the model. + *
+ * TOOL_CALL: A request from the model for the client to execute one or more functions. + *
+ * TOOL_CALL_CANCELLATION: Notification to cancel a previous function call triggered by {@link LiveServerToolCall}. + * * @beta */ export const LiveResponseType = { @@ -488,12 +495,5 @@ export const LiveResponseType = { TOOL_CALL_CANCELLATION: 'toolCallCancellation' }; -/** - * The types of responses that can be returned by {@link LiveSession.receive}. - * This is a property on all messages that can be used for type narrowing. This property is not - * returned by the server, it is assigned to a server message object once it's parsed. - * - * @beta - */ export type LiveResponseType = (typeof LiveResponseType)[keyof typeof LiveResponseType]; From f9142669b3bf3e0594535d5f069e729cc56e3ae2 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Tue, 23 Sep 2025 14:07:13 -0400 Subject: [PATCH 2/3] fix docs --- common/api-review/ai.api.md | 2 +- docs-devsite/ai.md | 7 +------ 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md index f1bd025a724..650ee17bb3d 100644 --- a/common/api-review/ai.api.md +++ b/common/api-review/ai.api.md @@ -953,7 +953,7 @@ export const LiveResponseType: { TOOL_CALL_CANCELLATION: string; }; -// @beta +// @public (undocumented) export type LiveResponseType = (typeof LiveResponseType)[keyof typeof LiveResponseType]; // @beta diff --git a/docs-devsite/ai.md b/docs-devsite/ai.md index 0178c01a10d..ec2b24ecfae 100644 --- a/docs-devsite/ai.md +++ b/docs-devsite/ai.md @@ -188,7 +188,7 @@ The Firebase AI Web SDK. | [LanguageModelMessageContentValue](./ai.md#languagemodelmessagecontentvalue) | (Public Preview) Content formats that can be provided as on-device message content. | | [LanguageModelMessageRole](./ai.md#languagemodelmessagerole) | (Public Preview) Allowable roles for on-device language model usage. | | [LanguageModelMessageType](./ai.md#languagemodelmessagetype) | (Public Preview) Allowable types for on-device language model messages. | -| [LiveResponseType](./ai.md#liveresponsetype) | (Public Preview) The types of responses that can be returned by [LiveSession.receive()](./ai.livesession.md#livesessionreceive). This is a property on all messages that can be used for type narrowing. This property is not returned by the server, it is assigned to a server message object once it's parsed. | +| [LiveResponseType](./ai.md#liveresponsetype) | | | [Modality](./ai.md#modality) | | | [Outcome](./ai.md#outcome) | Represents the result of the code execution. | | [Part](./ai.md#part) | Content part - includes text, image/video, or function call/response part types. | @@ -947,11 +947,6 @@ 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). This is a property on all messages that can be used for type narrowing. This property is not returned by the server, it is assigned to a server message object once it's parsed. - Signature: ```typescript From 72961eca1e3a30fe8a38eb5184f3d0834555b3ae Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Mon, 6 Oct 2025 13:57:55 -0400 Subject: [PATCH 3/3] add top-level comments --- common/api-review/ai.api.md | 26 ++++----- docs-devsite/ai.md | 72 +++++++++++++++++++----- packages/ai/src/public-types.ts | 12 ++++ packages/ai/src/types/enums.ts | 40 +++++++++++++ packages/ai/src/types/imagen/requests.ts | 32 +++++++++++ packages/ai/src/types/responses.ts | 5 ++ 6 files changed, 161 insertions(+), 26 deletions(-) diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md index 5e2e2b13521..d3c43d906fd 100644 --- a/common/api-review/ai.api.md +++ b/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 diff --git a/docs-devsite/ai.md b/docs-devsite/ai.md index 04d4994f45d..ce69048092e 100644 --- a/docs-devsite/ai.md +++ b/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) | (Public Preview) Aspect ratios for Imagen images. | +| [ImagenPersonFilterLevel](./ai.md#imagenpersonfilterlevel) | (Public Preview) A filter level controlling whether generation of images containing people or faces is allowed. | +| [ImagenSafetyFilterLevel](./ai.md#imagensafetyfilterlevel) | (Public Preview) A filter level controlling how aggressively to filter sensitive content. | | [InferenceMode](./ai.md#inferencemode) | (Public Preview) Determines whether inference happens on-device or in-cloud. | | [Language](./ai.md#language) | (Public Preview) The programming language of the code. | | [LanguageModelMessageContentValue](./ai.md#languagemodelmessagecontentvalue) | (Public Preview) Content formats that can be provided as on-device message content. | | [LanguageModelMessageRole](./ai.md#languagemodelmessagerole) | (Public Preview) Allowable roles for on-device language model usage. | | [LanguageModelMessageType](./ai.md#languagemodelmessagetype) | (Public Preview) Allowable types for on-device language model messages. | -| [LiveResponseType](./ai.md#liveresponsetype) | | -| [Modality](./ai.md#modality) | | +| [LiveResponseType](./ai.md#liveresponsetype) | (Public Preview) 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) | (Public Preview) 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) | (Public Preview) 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. + Signature: ```typescript @@ -829,6 +833,8 @@ export type BackendType = (typeof BackendType)[keyof typeof BackendType]; ## BlockReason +Reason that a prompt was blocked. + Signature: ```typescript @@ -837,6 +843,8 @@ export type BlockReason = (typeof BlockReason)[keyof typeof BlockReason]; ## FinishReason +Reason that a candidate finished. + Signature: ```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)). + Signature: ```typescript @@ -862,6 +872,8 @@ export type HarmBlockMethod = (typeof HarmBlockMethod)[keyof typeof HarmBlockMet ## HarmBlockThreshold +Threshold above which a prompt or candidate will be blocked. + Signature: ```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. + Signature: ```typescript @@ -878,6 +892,8 @@ export type HarmCategory = (typeof HarmCategory)[keyof typeof HarmCategory]; ## HarmProbability +Probability that a prompt or candidate matches a harm category. + Signature: ```typescript @@ -886,6 +902,8 @@ export type HarmProbability = (typeof HarmProbability)[keyof typeof HarmProbabil ## HarmSeverity +Harm severity levels. + Signature: ```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. + Signature: ```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 personGeneration documentation for more details. + Signature: ```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. + Signature: ```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). + Signature: ```typescript @@ -991,6 +1035,8 @@ export type LiveResponseType = (typeof LiveResponseType)[keyof typeof LiveRespon ## Modality +Content part modality. + Signature: ```typescript diff --git a/packages/ai/src/public-types.ts b/packages/ai/src/public-types.ts index ec756c5992a..3eb2a152356 100644 --- a/packages/ai/src/public-types.ts +++ b/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]; /** diff --git a/packages/ai/src/types/enums.ts b/packages/ai/src/types/enums.ts index 4917962badc..a0a6ef8cbad 100644 --- a/packages/ai/src/types/enums.ts +++ b/packages/ai/src/types/enums.ts @@ -68,6 +68,11 @@ export const HarmCategory = { HARM_CATEGORY_DANGEROUS_CONTENT: 'HARM_CATEGORY_DANGEROUS_CONTENT' } as const; +/** + * Harm categories that would cause prompts or candidates to be blocked. + * + * @public + */ export type HarmCategory = (typeof HarmCategory)[keyof typeof HarmCategory]; /** @@ -95,6 +100,11 @@ export const HarmBlockThreshold = { OFF: 'OFF' } as const; +/** + * Threshold above which a prompt or candidate will be blocked. + * + * @public + */ export type HarmBlockThreshold = (typeof HarmBlockThreshold)[keyof typeof HarmBlockThreshold]; @@ -113,6 +123,11 @@ export const HarmBlockMethod = { PROBABILITY: 'PROBABILITY' } as const; +/** + * This property is not supported in the Gemini Developer API ({@link GoogleAIBackend}). + * + * @public + */ export type HarmBlockMethod = (typeof HarmBlockMethod)[keyof typeof HarmBlockMethod]; @@ -137,6 +152,11 @@ export const HarmProbability = { HIGH: 'HIGH' } as const; +/** + * Probability that a prompt or candidate matches a harm category. + * + * @public + */ export type HarmProbability = (typeof HarmProbability)[keyof typeof HarmProbability]; @@ -164,6 +184,11 @@ export const HarmSeverity = { HARM_SEVERITY_UNSUPPORTED: 'HARM_SEVERITY_UNSUPPORTED' } as const; +/** + * Harm severity levels. + * + * @public + */ export type HarmSeverity = (typeof HarmSeverity)[keyof typeof HarmSeverity]; /** @@ -187,6 +212,11 @@ export const BlockReason = { PROHIBITED_CONTENT: 'PROHIBITED_CONTENT' } as const; +/** + * Reason that a prompt was blocked. + * + * @public + */ export type BlockReason = (typeof BlockReason)[keyof typeof BlockReason]; /** @@ -225,6 +255,11 @@ export const FinishReason = { MALFORMED_FUNCTION_CALL: 'MALFORMED_FUNCTION_CALL' } as const; +/** + * Reason that a candidate finished. + * + * @public + */ export type FinishReason = (typeof FinishReason)[keyof typeof FinishReason]; /** @@ -280,6 +315,11 @@ export const Modality = { DOCUMENT: 'DOCUMENT' } as const; +/** + * Content part modality. + * + * @public + */ export type Modality = (typeof Modality)[keyof typeof Modality]; /** diff --git a/packages/ai/src/types/imagen/requests.ts b/packages/ai/src/types/imagen/requests.ts index 216b91c77ae..691f1d137df 100644 --- a/packages/ai/src/types/imagen/requests.ts +++ b/packages/ai/src/types/imagen/requests.ts @@ -128,6 +128,19 @@ export const ImagenSafetyFilterLevel = { BLOCK_NONE: 'block_none' } as const; +/** + * A filter level controlling how aggressively to filter sensitive content. + * + * @remarks + * 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 {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } + * and the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters | Responsible AI and usage guidelines} + * for more details. + * + * @beta + */ export type ImagenSafetyFilterLevel = (typeof ImagenSafetyFilterLevel)[keyof typeof ImagenSafetyFilterLevel]; @@ -158,6 +171,15 @@ export const ImagenPersonFilterLevel = { ALLOW_ALL: 'allow_all' } as const; +/** + * A filter level controlling whether generation of images containing people or faces is allowed. + * + * @remarks + * See the personGeneration + * documentation for more details. + * + * @beta + */ export type ImagenPersonFilterLevel = (typeof ImagenPersonFilterLevel)[keyof typeof ImagenPersonFilterLevel]; @@ -209,5 +231,15 @@ export const ImagenAspectRatio = { 'PORTRAIT_9x16': '9:16' } as const; +/** + * Aspect ratios for Imagen images. + * + * @remarks + * To specify an aspect ratio for generated images, set the `aspectRatio` property in your + * {@link ImagenGenerationConfig}. See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } + * for more details and examples of the supported aspect ratios. + * + * @beta + */ export type ImagenAspectRatio = (typeof ImagenAspectRatio)[keyof typeof ImagenAspectRatio]; diff --git a/packages/ai/src/types/responses.ts b/packages/ai/src/types/responses.ts index e85c430582f..a7a584ecc83 100644 --- a/packages/ai/src/types/responses.ts +++ b/packages/ai/src/types/responses.ts @@ -592,5 +592,10 @@ export const LiveResponseType = { TOOL_CALL_CANCELLATION: 'toolCallCancellation' }; +/** + * The types of responses that can be returned by {@link LiveSession.receive}. + * + * @beta + */ export type LiveResponseType = (typeof LiveResponseType)[keyof typeof LiveResponseType];