@firebase/ai 2.1.0-canary.5501791d0 → 2.1.0-canary.9b63cd60e

package/dist/ai-public.d.ts

@@ -4,10 +4,17 @@
  * @packageDocumentation
  */
 
+import { AppCheckInternalComponentName } from '@firebase/app-check-interop-types';
 import { AppCheckTokenResult } from '@firebase/app-check-interop-types';
+import { ComponentContainer } from '@firebase/component';
 import { FirebaseApp } from '@firebase/app';
+import { FirebaseAppCheckInternal } from '@firebase/app-check-interop-types';
+import { FirebaseAuthInternal } from '@firebase/auth-interop-types';
+import { FirebaseAuthInternalName } from '@firebase/auth-interop-types';
 import { FirebaseAuthTokenData } from '@firebase/auth-interop-types';
 import { FirebaseError } from '@firebase/util';
+import { InstanceFactoryOptions } from '@firebase/component';
+import { Provider } from '@firebase/component';
 
 /**
  * An instance of the Firebase AI SDK.
@@ -27,6 +34,10 @@ export declare interface AI {
      * Vertex AI Gemini API (using {@link VertexAIBackend}).
      */
     backend: Backend;
+    /**
+     * Options applied to this {@link AI} instance.
+     */
+    options?: AIOptions;
     /**
      * @deprecated use `AI.backend.location` instead.
      *
@@ -125,8 +136,26 @@ export declare abstract class AIModel {
 export declare interface AIOptions {
     /**
      * The backend configuration to use for the AI service instance.
+     * Defaults to the Gemini Developer API backend ({@link GoogleAIBackend}).
+     */
+    backend?: Backend;
+    /**
+     * Whether to use App Check limited use tokens. Defaults to false.
      */
+    useLimitedUseAppCheckTokens?: boolean;
+}
+
+declare class AIService implements AI, _FirebaseService {
+    app: FirebaseApp;
     backend: Backend;
+    auth: FirebaseAuthInternal | null;
+    appCheck: FirebaseAppCheckInternal | null;
+    _options?: Omit<AIOptions, 'backend'>;
+    location: string;
+    constructor(app: FirebaseApp, backend: Backend, authProvider?: Provider<FirebaseAuthInternalName>, appCheckProvider?: Provider<AppCheckInternalComponentName>);
+    _delete(): Promise<void>;
+    set options(optionsToSet: AIOptions);
+    get options(): AIOptions | undefined;
 }
 
 /**
@@ -459,15 +488,34 @@ export declare interface EnhancedGenerateContentResponse extends GenerateContent
      */
     text: () => string;
     /**
-     * Aggregates and returns all {@link InlineDataPart}s from the {@link GenerateContentResponse}'s
-     * first candidate.
-     *
-     * @returns An array of {@link InlineDataPart}s containing data from the response, if available.
+     * Aggregates and returns every {@link InlineDataPart} from the first candidate of
+     * {@link GenerateContentResponse}.
      *
      * @throws If the prompt or candidate was blocked.
      */
     inlineDataParts: () => InlineDataPart[] | undefined;
+    /**
+     * Aggregates and returns every {@link FunctionCall} from the first candidate of
+     * {@link GenerateContentResponse}.
+     *
+     * @throws If the prompt or candidate was blocked.
+     */
     functionCalls: () => FunctionCall[] | undefined;
+    /**
+     * Aggregates and returns every {@link TextPart} with their `thought` property set
+     * to `true` from the first candidate of {@link GenerateContentResponse}.
+     *
+     * @throws If the prompt or candidate was blocked.
+     *
+     * @remarks
+     * 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 {@link ThinkingConfig.includeThoughts} is
+     * set to `true`.
+     */
+    thoughtSummary: () => string | undefined;
 }
 
 /**
@@ -487,6 +535,8 @@ export declare interface ErrorDetails {
     [key: string]: unknown;
 }
 
+export declare function factory(container: ComponentContainer, { instanceIdentifier }: InstanceFactoryOptions): AIService;
+
 /**
  * Data pointing to a file uploaded on Google Cloud Storage.
  * @public
@@ -506,6 +556,8 @@ export declare interface FileDataPart {
     functionCall?: never;
     functionResponse?: never;
     fileData: FileData;
+    thought?: boolean;
+    /* Excluded from this release type: thoughtSignature */
 }
 
 /**
@@ -557,6 +609,8 @@ export declare const FinishReason: {
  */
 export declare type FinishReason = (typeof FinishReason)[keyof typeof FinishReason];
 
+/* Excluded from this release type: _FirebaseService */
+
 /**
  * A predicted {@link FunctionCall} returned from the model
  * that contains a string representing the {@link FunctionDeclaration.name}
@@ -613,6 +667,8 @@ export declare interface FunctionCallPart {
     inlineData?: never;
     functionCall: FunctionCall;
     functionResponse?: never;
+    thought?: boolean;
+    /* Excluded from this release type: thoughtSignature */
 }
 
 /**
@@ -687,6 +743,8 @@ export declare interface FunctionResponsePart {
     inlineData?: never;
     functionCall?: never;
     functionResponse: FunctionResponse;
+    thought?: boolean;
+    /* Excluded from this release type: thoughtSignature */
 }
 
 /**
@@ -1665,6 +1723,8 @@ export declare interface InlineDataPart {
      * Applicable if `inlineData` is a video.
      */
     videoMetadata?: VideoMetadata;
+    thought?: boolean;
+    /* Excluded from this release type: thoughtSignature */
 }
 
 /**
@@ -2279,6 +2339,8 @@ export declare interface TextPart {
     inlineData?: never;
     functionCall?: never;
     functionResponse?: never;
+    thought?: boolean;
+    /* Excluded from this release type: thoughtSignature */
 }
 
 /**
@@ -2304,6 +2366,15 @@ export declare interface ThinkingConfig {
      * feature or if the specified budget is not within the model's supported range.
      */
     thinkingBudget?: number;
+    /**
+     * Whether to include "thought summaries" in the model's response.
+     *
+     * @remarks
+     * 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.
+     */
+    includeThoughts?: boolean;
 }
 
 /**

package/dist/ai.d.ts

@@ -4,10 +4,18 @@
  * @packageDocumentation
  */
 
+import { AppCheckInternalComponentName } from '@firebase/app-check-interop-types';
 import { AppCheckTokenResult } from '@firebase/app-check-interop-types';
+import { ComponentContainer } from '@firebase/component';
 import { FirebaseApp } from '@firebase/app';
+import { FirebaseAppCheckInternal } from '@firebase/app-check-interop-types';
+import { FirebaseAuthInternal } from '@firebase/auth-interop-types';
+import { FirebaseAuthInternalName } from '@firebase/auth-interop-types';
 import { FirebaseAuthTokenData } from '@firebase/auth-interop-types';
 import { FirebaseError } from '@firebase/util';
+import { _FirebaseService } from '@firebase/app';
+import { InstanceFactoryOptions } from '@firebase/component';
+import { Provider } from '@firebase/component';
 
 /**
  * An instance of the Firebase AI SDK.
@@ -27,6 +35,10 @@ export declare interface AI {
      * Vertex AI Gemini API (using {@link VertexAIBackend}).
      */
     backend: Backend;
+    /**
+     * Options applied to this {@link AI} instance.
+     */
+    options?: AIOptions;
     /**
      * @deprecated use `AI.backend.location` instead.
      *
@@ -111,7 +123,7 @@ export declare abstract class AIModel {
     /**
      * @internal
      */
-    protected _apiSettings: ApiSettings;
+    _apiSettings: ApiSettings;
     /**
      * Constructs a new instance of the {@link AIModel} class.
      *
@@ -159,8 +171,26 @@ export declare abstract class AIModel {
 export declare interface AIOptions {
     /**
      * The backend configuration to use for the AI service instance.
+     * Defaults to the Gemini Developer API backend ({@link GoogleAIBackend}).
      */
+    backend?: Backend;
+    /**
+     * Whether to use App Check limited use tokens. Defaults to false.
+     */
+    useLimitedUseAppCheckTokens?: boolean;
+}
+
+declare class AIService implements AI, _FirebaseService {
+    app: FirebaseApp;
     backend: Backend;
+    auth: FirebaseAuthInternal | null;
+    appCheck: FirebaseAppCheckInternal | null;
+    _options?: Omit<AIOptions, 'backend'>;
+    location: string;
+    constructor(app: FirebaseApp, backend: Backend, authProvider?: Provider<FirebaseAuthInternalName>, appCheckProvider?: Provider<AppCheckInternalComponentName>);
+    _delete(): Promise<void>;
+    set options(optionsToSet: AIOptions);
+    get options(): AIOptions | undefined;
 }
 
 /**
@@ -502,15 +532,34 @@ export declare interface EnhancedGenerateContentResponse extends GenerateContent
      */
     text: () => string;
     /**
-     * Aggregates and returns all {@link InlineDataPart}s from the {@link GenerateContentResponse}'s
-     * first candidate.
-     *
-     * @returns An array of {@link InlineDataPart}s containing data from the response, if available.
+     * Aggregates and returns every {@link InlineDataPart} from the first candidate of
+     * {@link GenerateContentResponse}.
      *
      * @throws If the prompt or candidate was blocked.
      */
     inlineDataParts: () => InlineDataPart[] | undefined;
+    /**
+     * Aggregates and returns every {@link FunctionCall} from the first candidate of
+     * {@link GenerateContentResponse}.
+     *
+     * @throws If the prompt or candidate was blocked.
+     */
     functionCalls: () => FunctionCall[] | undefined;
+    /**
+     * Aggregates and returns every {@link TextPart} with their `thought` property set
+     * to `true` from the first candidate of {@link GenerateContentResponse}.
+     *
+     * @throws If the prompt or candidate was blocked.
+     *
+     * @remarks
+     * 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 {@link ThinkingConfig.includeThoughts} is
+     * set to `true`.
+     */
+    thoughtSummary: () => string | undefined;
 }
 
 /**
@@ -530,6 +579,8 @@ export declare interface ErrorDetails {
     [key: string]: unknown;
 }
 
+export declare function factory(container: ComponentContainer, { instanceIdentifier }: InstanceFactoryOptions): AIService;
+
 /**
  * Data pointing to a file uploaded on Google Cloud Storage.
  * @public
@@ -549,6 +600,11 @@ export declare interface FileDataPart {
     functionCall?: never;
     functionResponse?: never;
     fileData: FileData;
+    thought?: boolean;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
 }
 
 /**
@@ -656,6 +712,11 @@ export declare interface FunctionCallPart {
     inlineData?: never;
     functionCall: FunctionCall;
     functionResponse?: never;
+    thought?: boolean;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
 }
 
 /**
@@ -730,6 +791,11 @@ export declare interface FunctionResponsePart {
     inlineData?: never;
     functionCall?: never;
     functionResponse: FunctionResponse;
+    thought?: boolean;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
 }
 
 /**
@@ -1761,6 +1827,11 @@ export declare interface InlineDataPart {
      * Applicable if `inlineData` is a video.
      */
     videoMetadata?: VideoMetadata;
+    thought?: boolean;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
 }
 
 /**
@@ -2386,6 +2457,11 @@ export declare interface TextPart {
     inlineData?: never;
     functionCall?: never;
     functionResponse?: never;
+    thought?: boolean;
+    /**
+     * @internal
+     */
+    thoughtSignature?: string;
 }
 
 /**
@@ -2411,6 +2487,15 @@ export declare interface ThinkingConfig {
      * feature or if the specified budget is not within the model's supported range.
      */
     thinkingBudget?: number;
+    /**
+     * Whether to include "thought summaries" in the model's response.
+     *
+     * @remarks
+     * 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.
+     */
+    includeThoughts?: boolean;
 }
 
 /**

package/dist/esm/index.esm.js

@@ -4,7 +4,7 @@ import { FirebaseError, getModularInstance } from '@firebase/util';
 import { Logger } from '@firebase/logger';
 
 var name = "@firebase/ai";
-var version = "2.1.0-canary.5501791d0";
+var version = "2.1.0-canary.9b63cd60e";
 
 /**
  * @license
@@ -653,6 +653,12 @@ class AIService {
     _delete() {
         return Promise.resolve();
     }
+    set options(optionsToSet) {
+        this._options = optionsToSet;
+    }
+    get options() {
+        return this._options;
+    }
 }
 
 /**
@@ -837,7 +843,12 @@ class AIModel {
                 };
             }
             else if (ai.appCheck) {
-                this._apiSettings.getAppCheckToken = () => ai.appCheck.getToken();
+                if (ai.options?.useLimitedUseAppCheckTokens) {
+                    this._apiSettings.getAppCheckToken = () => ai.appCheck.getLimitedUseToken();
+                }
+                else {
+                    this._apiSettings.getAppCheckToken = () => ai.appCheck.getToken();
+                }
             }
             if (ai.auth) {
                 this._apiSettings.getAuthToken = () => ai.auth.getToken();
@@ -1100,6 +1111,28 @@ async function makeRequest(model, task, apiSettings, stream, body, requestOption
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Check that at least one candidate exists and does not have a bad
+ * finish reason. Warns if multiple candidates exist.
+ */
+function hasValidCandidates(response) {
+    if (response.candidates && response.candidates.length > 0) {
+        if (response.candidates.length > 1) {
+            logger.warn(`This response had ${response.candidates.length} ` +
+                `candidates. Returning text from the first candidate only. ` +
+                `Access response.candidates directly to use the other candidates.`);
+        }
+        if (hadBadFinishReason(response.candidates[0])) {
+            throw new AIError(AIErrorCode.RESPONSE_ERROR, `Response error: ${formatBlockErrorMessage(response)}. Response body stored in error.response`, {
+                response
+            });
+        }
+        return true;
+    }
+    else {
+        return false;
+    }
+}
 /**
  * Creates an EnhancedGenerateContentResponse object that has helper functions and
  * other modifications that improve usability.
@@ -1123,18 +1156,8 @@ function createEnhancedContentResponse(response) {
  */
 function addHelpers(response) {
     response.text = () => {
-        if (response.candidates && response.candidates.length > 0) {
-            if (response.candidates.length > 1) {
-                logger.warn(`This response had ${response.candidates.length} ` +
-                    `candidates. Returning text from the first candidate only. ` +
-                    `Access response.candidates directly to use the other candidates.`);
-            }
-            if (hadBadFinishReason(response.candidates[0])) {
-                throw new AIError(AIErrorCode.RESPONSE_ERROR, `Response error: ${formatBlockErrorMessage(response)}. Response body stored in error.response`, {
-                    response
-                });
-            }
-            return getText(response);
+        if (hasValidCandidates(response)) {
+            return getText(response, part => !part.thought);
         }
         else if (response.promptFeedback) {
             throw new AIError(AIErrorCode.RESPONSE_ERROR, `Text not available. ${formatBlockErrorMessage(response)}`, {
@@ -1143,18 +1166,20 @@ function addHelpers(response) {
         }
         return '';
     };
+    response.thoughtSummary = () => {
+        if (hasValidCandidates(response)) {
+            const result = getText(response, part => !!part.thought);
+            return result === '' ? undefined : result;
+        }
+        else if (response.promptFeedback) {
+            throw new AIError(AIErrorCode.RESPONSE_ERROR, `Thought summary not available. ${formatBlockErrorMessage(response)}`, {
+                response
+            });
+        }
+        return undefined;
+    };
     response.inlineDataParts = () => {
-        if (response.candidates && response.candidates.length > 0) {
-            if (response.candidates.length > 1) {
-                logger.warn(`This response had ${response.candidates.length} ` +
-                    `candidates. Returning data from the first candidate only. ` +
-                    `Access response.candidates directly to use the other candidates.`);
-            }
-            if (hadBadFinishReason(response.candidates[0])) {
-                throw new AIError(AIErrorCode.RESPONSE_ERROR, `Response error: ${formatBlockErrorMessage(response)}. Response body stored in error.response`, {
-                    response
-                });
-            }
+        if (hasValidCandidates(response)) {
             return getInlineDataParts(response);
         }
         else if (response.promptFeedback) {
@@ -1165,17 +1190,7 @@ function addHelpers(response) {
         return undefined;
     };
     response.functionCalls = () => {
-        if (response.candidates && response.candidates.length > 0) {
-            if (response.candidates.length > 1) {
-                logger.warn(`This response had ${response.candidates.length} ` +
-                    `candidates. Returning function calls from the first candidate only. ` +
-                    `Access response.candidates directly to use the other candidates.`);
-            }
-            if (hadBadFinishReason(response.candidates[0])) {
-                throw new AIError(AIErrorCode.RESPONSE_ERROR, `Response error: ${formatBlockErrorMessage(response)}. Response body stored in error.response`, {
-                    response
-                });
-            }
+        if (hasValidCandidates(response)) {
             return getFunctionCalls(response);
         }
         else if (response.promptFeedback) {
@@ -1188,13 +1203,17 @@ function addHelpers(response) {
     return response;
 }
 /**
- * Returns all text found in all parts of first candidate.
+ * Returns all text from the first candidate's parts, filtering by whether
+ * `partFilter()` returns true.
+ *
+ * @param response - The `GenerateContentResponse` from which to extract text.
+ * @param partFilter - Only return `Part`s for which this returns true
  */
-function getText(response) {
+function getText(response, partFilter) {
     const textStrings = [];
     if (response.candidates?.[0].content?.parts) {
         for (const part of response.candidates?.[0].content?.parts) {
-            if (part.text) {
+            if (part.text && partFilter(part)) {
                 textStrings.push(part.text);
             }
         }
@@ -1207,7 +1226,7 @@ function getText(response) {
     }
 }
 /**
- * Returns {@link FunctionCall}s associated with first candidate.
+ * Returns every {@link FunctionCall} associated with first candidate.
  */
 function getFunctionCalls(response) {
     const functionCalls = [];
@@ -1226,7 +1245,7 @@ function getFunctionCalls(response) {
     }
 }
 /**
- * Returns {@link InlineDataPart}s in the first candidate if present.
+ * Returns every {@link InlineDataPart} in the first candidate if present.
  *
  * @internal
  */
@@ -1874,12 +1893,14 @@ const VALID_PART_FIELDS = [
     'text',
     'inlineData',
     'functionCall',
-    'functionResponse'
+    'functionResponse',
+    'thought',
+    'thoughtSignature'
 ];
 const VALID_PARTS_PER_ROLE = {
     user: ['text', 'inlineData'],
     function: ['functionResponse'],
-    model: ['text', 'functionCall'],
+    model: ['text', 'functionCall', 'thought', 'thoughtSignature'],
     // System instructions shouldn't be in history anyway.
     system: ['text']
 };
@@ -1901,7 +1922,7 @@ function validateChatHistory(history) {
             throw new AIError(AIErrorCode.INVALID_CONTENT, `Each item should include role field. Got ${role} but valid roles are: ${JSON.stringify(POSSIBLE_ROLES)}`);
         }
         if (!Array.isArray(parts)) {
-            throw new AIError(AIErrorCode.INVALID_CONTENT, `Content should have 'parts' but property with an array of Parts`);
+            throw new AIError(AIErrorCode.INVALID_CONTENT, `Content should have 'parts' property with an array of Parts`);
         }
         if (parts.length === 0) {
             throw new AIError(AIErrorCode.INVALID_CONTENT, `Each Content should have at least one part`);
@@ -1910,7 +1931,9 @@ function validateChatHistory(history) {
             text: 0,
             inlineData: 0,
             functionCall: 0,
-            functionResponse: 0
+            functionResponse: 0,
+            thought: 0,
+            thoughtSignature: 0
         };
         for (const part of parts) {
             for (const key of VALID_PART_FIELDS) {
@@ -2959,14 +2982,20 @@ class ImagenImageFormat {
  *
  * @public
  */
-function getAI(app = getApp(), options = { backend: new GoogleAIBackend() }) {
+function getAI(app = getApp(), options) {
     app = getModularInstance(app);
     // Dependencies
     const AIProvider = _getProvider(app, AI_TYPE);
-    const identifier = encodeInstanceIdentifier(options.backend);
-    return AIProvider.getImmediate({
+    const backend = options?.backend ?? new GoogleAIBackend();
+    const finalOptions = {
+        useLimitedUseAppCheckTokens: options?.useLimitedUseAppCheckTokens ?? false
+    };
+    const identifier = encodeInstanceIdentifier(backend);
+    const aiInstance = AIProvider.getImmediate({
         identifier
     });
+    aiInstance.options = finalOptions;
+    return aiInstance;
 }
 /**
  * Returns a {@link GenerativeModel} class with methods for inference
@@ -3022,23 +3051,24 @@ function getImagenModel(ai, modelParams, requestOptions) {
  *
  * @packageDocumentation
  */
+function factory(container, { instanceIdentifier }) {
+    if (!instanceIdentifier) {
+        throw new AIError(AIErrorCode.ERROR, 'AIService instance identifier is undefined.');
+    }
+    const backend = decodeInstanceIdentifier(instanceIdentifier);
+    // getImmediate for FirebaseApp will always succeed
+    const app = container.getProvider('app').getImmediate();
+    const auth = container.getProvider('auth-internal');
+    const appCheckProvider = container.getProvider('app-check-internal');
+    return new AIService(app, backend, auth, appCheckProvider);
+}
 function registerAI() {
-    _registerComponent(new Component(AI_TYPE, (container, { instanceIdentifier }) => {
-        if (!instanceIdentifier) {
-            throw new AIError(AIErrorCode.ERROR, 'AIService instance identifier is undefined.');
-        }
-        const backend = decodeInstanceIdentifier(instanceIdentifier);
-        // getImmediate for FirebaseApp will always succeed
-        const app = container.getProvider('app').getImmediate();
-        const auth = container.getProvider('auth-internal');
-        const appCheckProvider = container.getProvider('app-check-internal');
-        return new AIService(app, backend, auth, appCheckProvider);
-    }, "PUBLIC" /* ComponentType.PUBLIC */).setMultipleInstances(true));
+    _registerComponent(new Component(AI_TYPE, factory, "PUBLIC" /* ComponentType.PUBLIC */).setMultipleInstances(true));
     registerVersion(name, version);
     // BUILD_TARGET will be replaced by values like esm, cjs, etc during the compilation
     registerVersion(name, version, 'esm2020');
 }
 registerAI();
 
-export { AIError, AIErrorCode, AIModel, AnyOfSchema, ArraySchema, Backend, BackendType, BlockReason, BooleanSchema, ChatSession, FinishReason, FunctionCallingMode, GenerativeModel, GoogleAIBackend, HarmBlockMethod, HarmBlockThreshold, HarmCategory, HarmProbability, HarmSeverity, ImagenAspectRatio, ImagenImageFormat, ImagenModel, ImagenPersonFilterLevel, ImagenSafetyFilterLevel, InferenceMode, IntegerSchema, Modality, NumberSchema, ObjectSchema, POSSIBLE_ROLES, ResponseModality, Schema, SchemaType, StringSchema, VertexAIBackend, getAI, getGenerativeModel, getImagenModel };
+export { AIError, AIErrorCode, AIModel, AnyOfSchema, ArraySchema, Backend, BackendType, BlockReason, BooleanSchema, ChatSession, FinishReason, FunctionCallingMode, GenerativeModel, GoogleAIBackend, HarmBlockMethod, HarmBlockThreshold, HarmCategory, HarmProbability, HarmSeverity, ImagenAspectRatio, ImagenImageFormat, ImagenModel, ImagenPersonFilterLevel, ImagenSafetyFilterLevel, InferenceMode, IntegerSchema, Modality, NumberSchema, ObjectSchema, POSSIBLE_ROLES, ResponseModality, Schema, SchemaType, StringSchema, VertexAIBackend, factory, getAI, getGenerativeModel, getImagenModel };
 //# sourceMappingURL=index.esm.js.map