From afed1b273439b3bc9166772c553ab75637e8b754 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Tue, 8 Jul 2025 10:46:15 -0400 Subject: [PATCH 1/3] feat(ai): Add support for Thinking Budget --- common/api-review/ai.api.md | 7 +++ docs-devsite/_toc.yaml | 2 + docs-devsite/ai.generationconfig.md | 11 +++++ docs-devsite/ai.md | 1 + docs-devsite/ai.thinkingconfig.md | 43 +++++++++++++++++++ docs-devsite/ai.usagemetadata.md | 11 +++++ .../ai/integration/generate-content.test.ts | 4 ++ packages/ai/src/types/requests.ts | 29 +++++++++++++ packages/ai/src/types/responses.ts | 4 ++ 9 files changed, 112 insertions(+) create mode 100644 docs-devsite/ai.thinkingconfig.md diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md index ab79447798f..265bd492ff8 100644 --- a/common/api-review/ai.api.md +++ b/common/api-review/ai.api.md @@ -381,6 +381,7 @@ export interface GenerationConfig { stopSequences?: string[]; // (undocumented) temperature?: number; + thinkingConfig?: ThinkingConfig; // (undocumented) topK?: number; // (undocumented) @@ -901,6 +902,11 @@ export interface TextPart { text: string; } +// @public +export interface ThinkingConfig { + thinkingBudget?: number; +} + // @public export type Tool = FunctionDeclarationsTool; @@ -923,6 +929,7 @@ export interface UsageMetadata { promptTokenCount: number; // (undocumented) promptTokensDetails?: ModalityTokenCount[]; + thoughtsTokenCount?: number; // (undocumented) totalTokenCount: number; } diff --git a/docs-devsite/_toc.yaml b/docs-devsite/_toc.yaml index b77a6b5910e..f592e29094f 100644 --- a/docs-devsite/_toc.yaml +++ b/docs-devsite/_toc.yaml @@ -138,6 +138,8 @@ toc: path: /docs/reference/js/ai.stringschema.md - title: TextPart path: /docs/reference/js/ai.textpart.md + - title: ThinkingConfig + path: /docs/reference/js/ai.thinkingconfig.md - title: ToolConfig path: /docs/reference/js/ai.toolconfig.md - title: UsageMetadata diff --git a/docs-devsite/ai.generationconfig.md b/docs-devsite/ai.generationconfig.md index f9697a07454..e791bde9485 100644 --- a/docs-devsite/ai.generationconfig.md +++ b/docs-devsite/ai.generationconfig.md @@ -31,6 +31,7 @@ export interface GenerationConfig | [responseSchema](./ai.generationconfig.md#generationconfigresponseschema) | [TypedSchema](./ai.md#typedschema) \| [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) | Output response schema of the generated candidate text. This value can be a class generated with a [Schema](./ai.schema.md#schema_class) static method like Schema.string() or Schema.object() or it can be a plain JS object matching the [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) interface.
Note: This only applies when the specified responseMIMEType supports a schema; currently this is limited to application/json and text/x.enum. | | [stopSequences](./ai.generationconfig.md#generationconfigstopsequences) | string\[\] | | | [temperature](./ai.generationconfig.md#generationconfigtemperature) | number | | +| [thinkingConfig](./ai.generationconfig.md#generationconfigthinkingconfig) | [ThinkingConfig](./ai.thinkingconfig.md#thinkingconfig_interface) | Configuration for "thinking" behavior of compatible Gemini models. | | [topK](./ai.generationconfig.md#generationconfigtopk) | number | | | [topP](./ai.generationconfig.md#generationconfigtopp) | number | | @@ -117,6 +118,16 @@ stopSequences?: string[]; temperature?: number; ``` +## GenerationConfig.thinkingConfig + +Configuration for "thinking" behavior of compatible Gemini models. + +Signature: + +```typescript +thinkingConfig?: ThinkingConfig; +``` + ## GenerationConfig.topK Signature: diff --git a/docs-devsite/ai.md b/docs-devsite/ai.md index 286c8351fd7..136998df1ba 100644 --- a/docs-devsite/ai.md +++ b/docs-devsite/ai.md @@ -119,6 +119,7 @@ The Firebase AI Web SDK. | [Segment](./ai.segment.md#segment_interface) | | | [StartChatParams](./ai.startchatparams.md#startchatparams_interface) | Params for [GenerativeModel.startChat()](./ai.generativemodel.md#generativemodelstartchat). | | [TextPart](./ai.textpart.md#textpart_interface) | Content part interface if the part represents a text string. | +| [ThinkingConfig](./ai.thinkingconfig.md#thinkingconfig_interface) | Configuration for "thinking" behavior of compatible Gemini models.Certain models utilize a thinking process before generating a response. This allows them to reason through complex problems and plan a more coherent and accurate answer. | | [ToolConfig](./ai.toolconfig.md#toolconfig_interface) | Tool config. This config is shared for all tools provided in the request. | | [UsageMetadata](./ai.usagemetadata.md#usagemetadata_interface) | Usage metadata about a [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface). | | [VertexAIOptions](./ai.vertexaioptions.md#vertexaioptions_interface) | Options when initializing the Firebase AI SDK. | diff --git a/docs-devsite/ai.thinkingconfig.md b/docs-devsite/ai.thinkingconfig.md new file mode 100644 index 00000000000..ec348a20487 --- /dev/null +++ b/docs-devsite/ai.thinkingconfig.md @@ -0,0 +1,43 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# ThinkingConfig interface +Configuration for "thinking" behavior of compatible Gemini models. + +Certain models utilize a thinking process before generating a response. This allows them to reason through complex problems and plan a more coherent and accurate answer. + +Signature: + +```typescript +export interface ThinkingConfig +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [thinkingBudget](./ai.thinkingconfig.md#thinkingconfigthinkingbudget) | number | The thinking budget, in tokens.This parameter sets an upper limit on the number of tokens the model can use for its internal "thinking" process. A higher budget may result in higher quality responses for complex tasks but can also increase latency and cost.If you don't specify a budget, the model will determine the appropriate amount of thinking based on the complexity of the prompt.An error will be thrown if you set a thinking budget for a model that does not support this feature or if the specified budget is not within the model's supported range. | + +## ThinkingConfig.thinkingBudget + +The thinking budget, in tokens. + +This parameter sets an upper limit on the number of tokens the model can use for its internal "thinking" process. A higher budget may result in higher quality responses for complex tasks but can also increase latency and cost. + +If you don't specify a budget, the model will determine the appropriate amount of thinking based on the complexity of the prompt. + +An error will be thrown if you set a thinking budget for a model that does not support this feature or if the specified budget is not within the model's supported range. + +Signature: + +```typescript +thinkingBudget?: number; +``` diff --git a/docs-devsite/ai.usagemetadata.md b/docs-devsite/ai.usagemetadata.md index 4211fea72b4..954fcc6e530 100644 --- a/docs-devsite/ai.usagemetadata.md +++ b/docs-devsite/ai.usagemetadata.md @@ -26,6 +26,7 @@ export interface UsageMetadata | [candidatesTokensDetails](./ai.usagemetadata.md#usagemetadatacandidatestokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)\[\] | | | [promptTokenCount](./ai.usagemetadata.md#usagemetadataprompttokencount) | number | | | [promptTokensDetails](./ai.usagemetadata.md#usagemetadataprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)\[\] | | +| [thoughtsTokenCount](./ai.usagemetadata.md#usagemetadatathoughtstokencount) | number | The number of tokens used by the model's internal "thinking" process. | | [totalTokenCount](./ai.usagemetadata.md#usagemetadatatotaltokencount) | number | | ## UsageMetadata.candidatesTokenCount @@ -60,6 +61,16 @@ promptTokenCount: number; promptTokensDetails?: ModalityTokenCount[]; ``` +## UsageMetadata.thoughtsTokenCount + +The number of tokens used by the model's internal "thinking" process. + +Signature: + +```typescript +thoughtsTokenCount?: number; +``` + ## UsageMetadata.totalTokenCount Signature: diff --git a/packages/ai/integration/generate-content.test.ts b/packages/ai/integration/generate-content.test.ts index 22e4b0a30ac..f0d6e3f0b11 100644 --- a/packages/ai/integration/generate-content.test.ts +++ b/packages/ai/integration/generate-content.test.ts @@ -91,6 +91,10 @@ describe('Generate Content', () => { 2, TOKEN_COUNT_DELTA ); + expect(response.usageMetadata!.thoughtsTokenCount).to.be.closeTo( + 30, + TOKEN_COUNT_DELTA * 2 + ); expect(response.usageMetadata!.totalTokenCount).to.be.closeTo( 55, TOKEN_COUNT_DELTA * 2 diff --git a/packages/ai/src/types/requests.ts b/packages/ai/src/types/requests.ts index 67f45095c2a..87f2871a145 100644 --- a/packages/ai/src/types/requests.ts +++ b/packages/ai/src/types/requests.ts @@ -113,6 +113,10 @@ export interface GenerationConfig { * @beta */ responseModalities?: ResponseModality[]; + /** + * Configuration for "thinking" behavior of compatible Gemini models. + */ + thinkingConfig?: ThinkingConfig; } /** @@ -231,3 +235,28 @@ export interface FunctionCallingConfig { mode?: FunctionCallingMode; allowedFunctionNames?: string[]; } + +/** + * Configuration for "thinking" behavior of compatible Gemini models. + * + * Certain models utilize a thinking process before generating a response. This allows them to + * reason through complex problems and plan a more coherent and accurate answer. + * + * @public + */ +export interface ThinkingConfig { + /** + * The thinking budget, in tokens. + * + * This parameter sets an upper limit on the number of tokens the model can use for its internal + * "thinking" process. A higher budget may result in higher quality responses for complex tasks + * but can also increase latency and cost. + * + * If you don't specify a budget, the model will determine the appropriate amount + * of thinking based on the complexity of the prompt. + * + * An error will be thrown if you set a thinking budget for a model that does not support this + * feature or if the specified budget is not within the model's supported range. + */ + thinkingBudget?: number; +} diff --git a/packages/ai/src/types/responses.ts b/packages/ai/src/types/responses.ts index 8072e06fd02..8a1f9b6781d 100644 --- a/packages/ai/src/types/responses.ts +++ b/packages/ai/src/types/responses.ts @@ -92,6 +92,10 @@ export interface GenerateContentResponse { export interface UsageMetadata { promptTokenCount: number; candidatesTokenCount: number; + /** + * The number of tokens used by the model's internal "thinking" process. + */ + thoughtsTokenCount?: number; totalTokenCount: number; promptTokensDetails?: ModalityTokenCount[]; candidatesTokensDetails?: ModalityTokenCount[]; From 4bf02fc47d91e83c3e5636d6a002f9c8fafd8b46 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Tue, 8 Jul 2025 10:59:01 -0400 Subject: [PATCH 2/3] add changeset --- .changeset/hip-impalas-divide.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/hip-impalas-divide.md diff --git a/.changeset/hip-impalas-divide.md b/.changeset/hip-impalas-divide.md new file mode 100644 index 00000000000..be8c0b501a7 --- /dev/null +++ b/.changeset/hip-impalas-divide.md @@ -0,0 +1,5 @@ +--- +'@firebase/ai': minor +--- + +Add support for Thinking Budget. From 181256f4545453b5984c1f7f715642d4d5ba6a29 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Tue, 8 Jul 2025 11:08:19 -0400 Subject: [PATCH 3/3] add firebase minor to changeset --- .changeset/hip-impalas-divide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.changeset/hip-impalas-divide.md b/.changeset/hip-impalas-divide.md index be8c0b501a7..49f7cb8836d 100644 --- a/.changeset/hip-impalas-divide.md +++ b/.changeset/hip-impalas-divide.md @@ -1,4 +1,5 @@ --- +'firebase': minor '@firebase/ai': minor ---