Implement thoughtSummary() method, add docs, changeset

hsubox76 · hsubox76 · commit 3f62f8a0a1ea · 2025-08-12T11:59:54.000-07:00
diff --git a/.changeset/brave-llamas-impress.md b/.changeset/brave-llamas-impress.md
@@ -0,0 +1,6 @@
+---
+'@firebase/ai': minor
+'firebase': minor
+---
+
+Add `thoughtSummary()` convenience method to `EnhancedGenerateContentResponse`.
diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md
@@ -204,11 +204,9 @@ export { Date_2 as Date }
 
 // @public
 export interface EnhancedGenerateContentResponse extends GenerateContentResponse {
-    // (undocumented)
     functionCalls: () => FunctionCall[] | undefined;
     inlineDataParts: () => InlineDataPart[] | undefined;
     text: () => string;
-    // (undocumented)
     thoughtSummary: () => string | undefined;
 }
 
@@ -244,8 +242,6 @@ export interface FileDataPart {
     text?: never;
     // (undocumented)
     thought?: boolean;
-    // (undocumented)
-    thoughtSignature?: string;
 }
 
 // @public
@@ -302,8 +298,6 @@ export interface FunctionCallPart {
     text?: never;
     // (undocumented)
     thought?: boolean;
-    // (undocumented)
-    thoughtSignature?: string;
 }
 
 // @public
@@ -338,8 +332,6 @@ export interface FunctionResponsePart {
     text?: never;
     // (undocumented)
     thought?: boolean;
-    // (undocumented)
-    thoughtSignature?: string;
 }
 
 // @public
@@ -707,8 +699,6 @@ export interface InlineDataPart {
     text?: never;
     // (undocumented)
     thought?: boolean;
-    // (undocumented)
-    thoughtSignature?: string;
     videoMetadata?: VideoMetadata;
 }
 
@@ -977,8 +967,6 @@ export interface TextPart {
     text: string;
     // (undocumented)
     thought?: boolean;
-    // (undocumented)
-    thoughtSignature?: string;
 }
 
 // @public
diff --git a/docs-devsite/ai.enhancedgeneratecontentresponse.md b/docs-devsite/ai.enhancedgeneratecontentresponse.md
@@ -23,12 +23,15 @@ export interface EnhancedGenerateContentResponse extends GenerateContentResponse
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [functionCalls](./ai.enhancedgeneratecontentresponse.md#enhancedgeneratecontentresponsefunctioncalls) | () =&gt; [FunctionCall](./ai.functioncall.md#functioncall_interface)<!-- -->\[\] \| undefined |  |
+|  [functionCalls](./ai.enhancedgeneratecontentresponse.md#enhancedgeneratecontentresponsefunctioncalls) | () =&gt; [FunctionCall](./ai.functioncall.md#functioncall_interface)<!-- -->\[\] \| undefined | Aggregates and returns all [FunctionCall](./ai.functioncall.md#functioncall_interface)<!-- -->s from the [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->'s first candidate. |
 |  [inlineDataParts](./ai.enhancedgeneratecontentresponse.md#enhancedgeneratecontentresponseinlinedataparts) | () =&gt; [InlineDataPart](./ai.inlinedatapart.md#inlinedatapart_interface)<!-- -->\[\] \| undefined | Aggregates and returns all [InlineDataPart](./ai.inlinedatapart.md#inlinedatapart_interface)<!-- -->s from the [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->'s first candidate. |
 |  [text](./ai.enhancedgeneratecontentresponse.md#enhancedgeneratecontentresponsetext) | () =&gt; string | Returns the text string from the response, if available. Throws if the prompt or candidate was blocked. |
+|  [thoughtSummary](./ai.enhancedgeneratecontentresponse.md#enhancedgeneratecontentresponsethoughtsummary) | () =&gt; string \| undefined | Aggregates and returns all [TextPart](./ai.textpart.md#textpart_interface)<!-- -->s with their <code>thought</code> property set to <code>true</code> from the [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->'s first candidate. |
 
 ## EnhancedGenerateContentResponse.functionCalls
 
+Aggregates and returns all [FunctionCall](./ai.functioncall.md#functioncall_interface)<!-- -->s from the [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->'s first candidate.
+
 <b>Signature:</b>
 
 ```typescript
@@ -54,3 +57,17 @@ Returns the text string from the response, if available. Throws if the prompt or
 ```typescript
 text: () => string;
 ```
+
+## EnhancedGenerateContentResponse.thoughtSummary
+
+Aggregates and returns all [TextPart](./ai.textpart.md#textpart_interface)<!-- -->s with their `thought` property set to `true` from the [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->'s first candidate.
+
+Thought summaries provide a brief overview of the model's internal thinking process, offering insight into how it arrived at the final answer. This can be useful for debugging, understanding the model's reasoning, and verifying its accuracy.
+
+Thoughts will only be included if [ThinkingConfig.includeThoughts](./ai.thinkingconfig.md#thinkingconfigincludethoughts) is set to `true`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+thoughtSummary: () => string | undefined;
+```
diff --git a/docs-devsite/ai.filedatapart.md b/docs-devsite/ai.filedatapart.md
@@ -27,6 +27,7 @@ export interface FileDataPart
 |  [functionResponse](./ai.filedatapart.md#filedatapartfunctionresponse) | never |  |
 |  [inlineData](./ai.filedatapart.md#filedatapartinlinedata) | never |  |
 |  [text](./ai.filedatapart.md#filedataparttext) | never |  |
+|  [thought](./ai.filedatapart.md#filedatapartthought) | boolean |  |
 
 ## FileDataPart.fileData
 
@@ -67,3 +68,11 @@ inlineData?: never;
 ```typescript
 text?: never;
 ```
+
+## FileDataPart.thought
+
+<b>Signature:</b>
+
+```typescript
+thought?: boolean;
+```
diff --git a/docs-devsite/ai.functioncallpart.md b/docs-devsite/ai.functioncallpart.md
@@ -26,6 +26,7 @@ export interface FunctionCallPart
 |  [functionResponse](./ai.functioncallpart.md#functioncallpartfunctionresponse) | never |  |
 |  [inlineData](./ai.functioncallpart.md#functioncallpartinlinedata) | never |  |
 |  [text](./ai.functioncallpart.md#functioncallparttext) | never |  |
+|  [thought](./ai.functioncallpart.md#functioncallpartthought) | boolean |  |
 
 ## FunctionCallPart.functionCall
 
@@ -58,3 +59,11 @@ inlineData?: never;
 ```typescript
 text?: never;
 ```
+
+## FunctionCallPart.thought
+
+<b>Signature:</b>
+
+```typescript
+thought?: boolean;
+```
diff --git a/docs-devsite/ai.functionresponsepart.md b/docs-devsite/ai.functionresponsepart.md
@@ -26,6 +26,7 @@ export interface FunctionResponsePart
 |  [functionResponse](./ai.functionresponsepart.md#functionresponsepartfunctionresponse) | [FunctionResponse](./ai.functionresponse.md#functionresponse_interface) |  |
 |  [inlineData](./ai.functionresponsepart.md#functionresponsepartinlinedata) | never |  |
 |  [text](./ai.functionresponsepart.md#functionresponseparttext) | never |  |
+|  [thought](./ai.functionresponsepart.md#functionresponsepartthought) | boolean |  |
 
 ## FunctionResponsePart.functionCall
 
@@ -58,3 +59,11 @@ inlineData?: never;
 ```typescript
 text?: never;
 ```
+
+## FunctionResponsePart.thought
+
+<b>Signature:</b>
+
+```typescript
+thought?: boolean;
+```
diff --git a/docs-devsite/ai.inlinedatapart.md b/docs-devsite/ai.inlinedatapart.md
@@ -26,6 +26,7 @@ export interface InlineDataPart
 |  [functionResponse](./ai.inlinedatapart.md#inlinedatapartfunctionresponse) | never |  |
 |  [inlineData](./ai.inlinedatapart.md#inlinedatapartinlinedata) | [GenerativeContentBlob](./ai.generativecontentblob.md#generativecontentblob_interface) |  |
 |  [text](./ai.inlinedatapart.md#inlinedataparttext) | never |  |
+|  [thought](./ai.inlinedatapart.md#inlinedatapartthought) | boolean |  |
 |  [videoMetadata](./ai.inlinedatapart.md#inlinedatapartvideometadata) | [VideoMetadata](./ai.videometadata.md#videometadata_interface) | Applicable if <code>inlineData</code> is a video. |
 
 ## InlineDataPart.functionCall
@@ -60,6 +61,14 @@ inlineData: GenerativeContentBlob;
 text?: never;
 ```
 
+## InlineDataPart.thought
+
+<b>Signature:</b>
+
+```typescript
+thought?: boolean;
+```
+
 ## InlineDataPart.videoMetadata
 
 Applicable if `inlineData` is a video.
diff --git a/docs-devsite/ai.textpart.md b/docs-devsite/ai.textpart.md
@@ -26,6 +26,7 @@ export interface TextPart
 |  [functionResponse](./ai.textpart.md#textpartfunctionresponse) | never |  |
 |  [inlineData](./ai.textpart.md#textpartinlinedata) | never |  |
 |  [text](./ai.textpart.md#textparttext) | string |  |
+|  [thought](./ai.textpart.md#textpartthought) | boolean |  |
 
 ## TextPart.functionCall
 
@@ -58,3 +59,11 @@ inlineData?: never;
 ```typescript
 text: string;
 ```
+
+## TextPart.thought
+
+<b>Signature:</b>
+
+```typescript
+thought?: boolean;
+```
diff --git a/docs-devsite/ai.thinkingconfig.md b/docs-devsite/ai.thinkingconfig.md
@@ -24,8 +24,21 @@ export interface ThinkingConfig
 
 |  Property | Type | Description |
 |  --- | --- | --- |
+|  [includeThoughts](./ai.thinkingconfig.md#thinkingconfigincludethoughts) | boolean | Whether to include "thought summaries" in the model's response. |
 |  [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.includeThoughts
+
+Whether to include "thought summaries" in the model's response.
+
+Thought summaries provide a brief overview of the model's internal thinking process, offering insight into how it arrived at the final answer. This can be useful for debugging, understanding the model's reasoning, and verifying its accuracy.
+
+<b>Signature:</b>
+
+```typescript
+includeThoughts?: boolean;
+```
+
 ## ThinkingConfig.thinkingBudget
 
 The thinking budget, in tokens.
diff --git a/packages/ai/src/methods/chat-session-helpers.ts b/packages/ai/src/methods/chat-session-helpers.ts
@@ -80,7 +80,8 @@ export function validateChatHistory(history: Content[]): void {
       text: 0,
       inlineData: 0,
       functionCall: 0,
-      functionResponse: 0
+      functionResponse: 0,
+      thought: 0
     };
 
     for (const part of parts) {
diff --git a/packages/ai/src/requests/response-helpers.test.ts b/packages/ai/src/requests/response-helpers.test.ts
@@ -48,6 +48,21 @@ const fakeResponseText: GenerateContentResponse = {
   ]
 };
 
+const fakeResponseThoughts: GenerateContentResponse = {
+  candidates: [
+    {
+      index: 0,
+      content: {
+        role: 'model',
+        parts: [
+          { text: 'Some text' },
+          { text: 'and some thoughts', thought: true }
+        ]
+      }
+    }
+  ]
+};
+
 const functionCallPart1 = {
   functionCall: {
     name: 'find_theaters',
@@ -188,6 +203,7 @@ describe('response-helpers methods', () => {
       expect(enhancedResponse.text()).to.equal('Some text and some more text');
       expect(enhancedResponse.functionCalls()).to.be.undefined;
       expect(enhancedResponse.inlineDataParts()).to.be.undefined;
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
     });
     it('good response functionCall', async () => {
       const enhancedResponse = addHelpers(fakeResponseFunctionCall);
@@ -196,6 +212,7 @@ describe('response-helpers methods', () => {
         functionCallPart1.functionCall
       ]);
       expect(enhancedResponse.inlineDataParts()).to.be.undefined;
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
     });
     it('good response functionCalls', async () => {
       const enhancedResponse = addHelpers(fakeResponseFunctionCalls);
@@ -205,6 +222,7 @@ describe('response-helpers methods', () => {
         functionCallPart2.functionCall
       ]);
       expect(enhancedResponse.inlineDataParts()).to.be.undefined;
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
     });
     it('good response text/functionCall', async () => {
       const enhancedResponse = addHelpers(fakeResponseMixed1);
@@ -213,6 +231,7 @@ describe('response-helpers methods', () => {
       ]);
       expect(enhancedResponse.text()).to.equal('some text');
       expect(enhancedResponse.inlineDataParts()).to.be.undefined;
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
     });
     it('good response functionCall/text', async () => {
       const enhancedResponse = addHelpers(fakeResponseMixed2);
@@ -221,24 +240,28 @@ describe('response-helpers methods', () => {
       ]);
       expect(enhancedResponse.text()).to.equal('some text');
       expect(enhancedResponse.inlineDataParts()).to.be.undefined;
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
     });
     it('good response text/functionCall/text', async () => {
       const enhancedResponse = addHelpers(fakeResponseMixed3);
       expect(enhancedResponse.functionCalls()).to.deep.equal([
         functionCallPart1.functionCall
       ]);
       expect(enhancedResponse.text()).to.equal('some text and more text');
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
       expect(enhancedResponse.inlineDataParts()).to.be.undefined;
     });
     it('bad response safety', async () => {
       const enhancedResponse = addHelpers(badFakeResponse);
       expect(enhancedResponse.text).to.throw('SAFETY');
+      expect(enhancedResponse.thoughtSummary).to.throw('SAFETY');
       expect(enhancedResponse.functionCalls).to.throw('SAFETY');
       expect(enhancedResponse.inlineDataParts).to.throw('SAFETY');
     });
     it('good response inlineData', async () => {
       const enhancedResponse = addHelpers(fakeResponseInlineData);
       expect(enhancedResponse.text()).to.equal('');
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
       expect(enhancedResponse.functionCalls()).to.be.undefined;
       expect(enhancedResponse.inlineDataParts()).to.deep.equal([
         inlineDataPart1,
@@ -248,11 +271,19 @@ describe('response-helpers methods', () => {
     it('good response text/inlineData', async () => {
       const enhancedResponse = addHelpers(fakeResponseTextAndInlineData);
       expect(enhancedResponse.text()).to.equal('Describe this:');
+      expect(enhancedResponse.thoughtSummary()).to.be.undefined;
       expect(enhancedResponse.functionCalls()).to.be.undefined;
       expect(enhancedResponse.inlineDataParts()).to.deep.equal([
         inlineDataPart1
       ]);
     });
+    it('good response text/thought', async () => {
+      const enhancedResponse = addHelpers(fakeResponseThoughts);
+      expect(enhancedResponse.text()).to.equal('Some text');
+      expect(enhancedResponse.thoughtSummary()).to.equal('and some thoughts');
+      expect(enhancedResponse.functionCalls()).to.be.undefined;
+      expect(enhancedResponse.inlineDataParts()).to.be.undefined;
+    });
   });
   describe('getBlockString', () => {
     it('has no promptFeedback or bad finishReason', async () => {
diff --git a/packages/ai/src/requests/response-helpers.ts b/packages/ai/src/requests/response-helpers.ts
diff --git a/packages/ai/src/types/content.ts b/packages/ai/src/types/content.ts
diff --git a/packages/ai/src/types/requests.ts b/packages/ai/src/types/requests.ts
diff --git a/packages/ai/src/types/responses.ts b/packages/ai/src/types/responses.ts
