@firebase/ai 2.11.1 → 2.12.0-20260505164105

package/dist/ai.d.ts

@@ -594,6 +594,26 @@ export declare interface Content {
     parts: Part[];
 }
 
+/**
+ * Enables context window compression to manage the model's context window.
+ *
+ * @remarks
+ * This mechanism prevents the context from exceeding a given length.
+ *
+ * @beta
+ */
+export declare interface ContextWindowCompressionConfig {
+    /**
+     * The number of tokens (before running a turn) that triggers the context
+     * window compression.
+     */
+    triggerTokens?: number;
+    /**
+     * The sliding window compression mechanism.
+     */
+    slidingWindow?: SlidingWindow;
+}
+
 /**
  * Params for calling {@link GenerativeModel.countTokens}
  * @public
@@ -833,6 +853,46 @@ export declare const FinishReason: {
      * The function call generated by the model was invalid.
      */
     readonly MALFORMED_FUNCTION_CALL: "MALFORMED_FUNCTION_CALL";
+    /**
+     * Token generation stopped because generated images contain safety violations.
+     */
+    readonly IMAGE_SAFETY: "IMAGE_SAFETY";
+    /**
+     * Image generation stopped because generated images have other prohibited content.
+     */
+    readonly IMAGE_PROHIBITED_CONTENT: "IMAGE_PROHIBITED_CONTENT";
+    /**
+     * Image generation stopped because of other miscellaneous issue.
+     */
+    readonly IMAGE_OTHER: "IMAGE_OTHER";
+    /**
+     * The model was expected to generate an image, but none was generated.
+     */
+    readonly NO_IMAGE: "NO_IMAGE";
+    /**
+     * Image generation stopped due to recitation.
+     */
+    readonly IMAGE_RECITATION: "IMAGE_RECITATION";
+    /**
+     * The response candidate content was flagged for using an unsupported language.
+     */
+    readonly LANGUAGE: "LANGUAGE";
+    /**
+     * Model generated a tool call but no tools were enabled in the request.
+     */
+    readonly UNEXPECTED_TOOL_CALL: "UNEXPECTED_TOOL_CALL";
+    /**
+     * Model called too many tools consecutively, thus the system exited execution.
+     */
+    readonly TOO_MANY_TOOL_CALLS: "TOO_MANY_TOOL_CALLS";
+    /**
+     * Request has at least one thought signature missing.
+     */
+    readonly MISSING_THOUGHT_SIGNATURE: "MISSING_THOUGHT_SIGNATURE";
+    /**
+     * Finished due to malformed response.
+     */
+    readonly MALFORMED_RESPONSE: "MALFORMED_RESPONSE";
 };
 
 /**
@@ -1124,6 +1184,11 @@ export declare interface GenerationConfig {
      * Configuration for "thinking" behavior of compatible Gemini models.
      */
     thinkingConfig?: ThinkingConfig;
+    /**
+     * Configuration options for generating images with Gemini models.
+     * @public
+     */
+    imageConfig?: ImageConfig;
 }
 
 /**
@@ -1338,6 +1403,66 @@ export declare interface GoogleAIGenerateContentResponse {
     usageMetadata?: UsageMetadata;
 }
 
+/**
+ * Specifies the Google Maps configuration.
+ *
+ * @public
+ */
+export declare interface GoogleMaps {
+    enableWidget?: boolean;
+}
+
+/**
+ * A grounding chunk from Google Maps.
+ *
+ * Important: If using Grounding with Google Maps, you are required to comply with the
+ * {@link https://cloud.google.com/terms/service-terms | Service Specific Terms} for "Grounding with Google Maps".
+ *
+ * @public
+ */
+export declare interface GoogleMapsGroundingChunk {
+    /**
+     * The URI of the place.
+     */
+    uri?: string;
+    /**
+     * The title of the place.
+     */
+    title?: string;
+    /**
+     * The text of the place answer.
+     */
+    text?: string;
+    /**
+     * This Place's resource name, in `places/{place_id}` format. This can be used to look up the
+     * place in the Google Maps API.
+     */
+    placeId?: string;
+}
+
+/**
+ * A tool that allows a Gemini model to connect to Google Maps to access and incorporate
+ * location-based information into its responses.
+ *
+ * Important: If using Grounding with Google Maps, you are required to comply with the
+ * "Grounding with Google Maps" usage requirements for your chosen API provider: {@link https://ai.google.dev/gemini-api/terms#grounding-with-google-maps | Gemini Developer API}
+ * or Vertex AI Gemini API (see {@link https://cloud.google.com/terms/service-terms | Service Terms}
+ * section within the Service Specific Terms).
+ *
+ * @public
+ */
+export declare interface GoogleMapsTool {
+    /**
+     * Specifies the Google Maps configuration.
+     *
+     * When using this feature, you are required to comply with the "Grounding with Google Maps"
+     * usage requirements for your chosen API provider: {@link https://ai.google.dev/gemini-api/terms#grounding-with-google-maps | Gemini Developer API}
+     * or Vertex AI Gemini API (see {@link https://cloud.google.com/terms/service-terms | Service Terms}
+     * section within the Service Specific Terms).
+     */
+    googleMaps: GoogleMaps;
+}
+
 /**
  * Specifies the Google Search configuration.
  *
@@ -1383,18 +1508,28 @@ export declare interface GroundingChunk {
      * Contains details if the grounding chunk is from a web source.
      */
     web?: WebGroundingChunk;
+    /**
+     * Contains details if the grounding chunk is from a Google Maps source.
+     */
+    maps?: GoogleMapsGroundingChunk;
 }
 
 /**
  * Metadata returned when grounding is enabled.
  *
- * Currently, only Grounding with Google Search is supported (see {@link GoogleSearchTool}).
+ * Currently, only Grounding with Google Search and Grounding with Google Maps are supported
+ * (see {@link GoogleSearchTool} and {@link GoogleMapsTool}, respectively).
  *
  * Important: If using Grounding with Google Search, you are required to comply with the
  * "Grounding with Google Search" usage requirements for your chosen API provider: {@link https://ai.google.dev/gemini-api/terms#grounding-with-google-search | Gemini Developer API}
  * or Vertex AI Gemini API (see {@link https://cloud.google.com/terms/service-terms | Service Terms}
  * section within the Service Specific Terms).
  *
+ * Important: If using Grounding with Google Maps, you are required to comply with the
+ * "Grounding with Google Maps" usage requirements for your chosen API provider: {@link https://ai.google.dev/gemini-api/terms#grounding-with-google-maps | Gemini Developer API}
+ * or Vertex AI Gemini API (see {@link https://cloud.google.com/terms/service-terms | Service Terms}
+ * section within the Service Specific Terms).
+ *
  * @public
  */
 export declare interface GroundingMetadata {
@@ -1423,6 +1558,12 @@ export declare interface GroundingMetadata {
      * @deprecated Use {@link GroundingSupport} instead.
      */
     retrievalQueries?: string[];
+    /**
+     * Resource name of the Google Maps widget context token that can be used with the
+     * `PlacesContextElement` widget in order to render contextual data. Only populated in the case
+     * that grounding with Google Maps is enabled.
+     */
+    googleMapsWidgetContextToken?: string;
 }
 
 /**
@@ -1604,6 +1745,65 @@ export declare interface HybridParams {
     inCloudParams?: ModelParams;
 }
 
+/**
+ * Configuration options for generating images with Gemini models.
+ * @public
+ */
+export declare interface ImageConfig {
+    /**
+     * The aspect ratio of generated images.
+     */
+    aspectRatio?: ImageConfigAspectRatio;
+    /**
+     * The size of the generated images.
+     */
+    imageSize?: ImageConfigImageSize;
+}
+
+/**
+ * Aspect ratios for generated images.
+ * @public
+ */
+export declare const ImageConfigAspectRatio: {
+    readonly SQUARE_1x1: "1:1";
+    readonly PORTRAIT_9x16: "9:16";
+    readonly LANDSCAPE_16x9: "16:9";
+    readonly PORTRAIT_3x4: "3:4";
+    readonly LANDSCAPE_4x3: "4:3";
+    readonly PORTRAIT_2x3: "2:3";
+    readonly LANDSCAPE_3x2: "3:2";
+    readonly PORTRAIT_4x5: "4:5";
+    readonly LANDSCAPE_5x4: "5:4";
+    readonly PORTRAIT_1x4: "1:4";
+    readonly LANDSCAPE_4x1: "4:1";
+    readonly PORTRAIT_1x8: "1:8";
+    readonly LANDSCAPE_8x1: "8:1";
+    readonly ULTRAWIDE_21x9: "21:9";
+};
+
+/**
+ * Aspect ratios for generated images.
+ * @public
+ */
+export declare type ImageConfigAspectRatio = (typeof ImageConfigAspectRatio)[keyof typeof ImageConfigAspectRatio];
+
+/**
+ * Sizes for generated images. For example, '1K' is 1024px, '2K' is 2048px, and '4K' is 4096px.
+ * @public
+ */
+export declare const ImageConfigImageSize: {
+    readonly SIZE_512: "512";
+    readonly SIZE_1K: "1K";
+    readonly SIZE_2K: "2K";
+    readonly SIZE_4K: "4K";
+};
+
+/**
+ * Sizes for generated images.
+ * @public
+ */
+export declare type ImageConfigImageSize = (typeof ImageConfigImageSize)[keyof typeof ImageConfigImageSize];
+
 /**
  * Aspect ratios for Imagen images.
  *
@@ -2316,6 +2516,40 @@ export declare interface LanguageModelPromptOptions {
     responseConstraint?: object;
 }
 
+/**
+ * An object that represents a latitude/longitude pair.
+ * @public
+ */
+export declare interface LatLng {
+    /**
+     * The latitude in degrees. It must be in the range `[-90.0, +90.0]`.
+     */
+    latitude?: number;
+    /**
+     * The longitude in degrees. It must be in the range `[-180.0, +180.0]`.
+     */
+    longitude?: number;
+}
+
+/**
+ * The first message in a Live session, used to configure generation options.
+ *
+ * @internal
+ */
+declare interface _LiveClientSetup {
+    setup: {
+        model: string;
+        generationConfig?: _LiveGenerationConfig;
+        tools?: Tool[];
+        toolConfig?: ToolConfig;
+        systemInstruction?: string | Part | Content;
+        inputAudioTranscription?: AudioTranscriptionConfig;
+        outputAudioTranscription?: AudioTranscriptionConfig;
+        sessionResumption?: SessionResumptionConfig;
+        contextWindowCompression?: ContextWindowCompressionConfig;
+    };
+}
+
 /**
  * Configuration parameters used by {@link LiveGenerativeModel} to control live content generation.
  *
@@ -2383,8 +2617,22 @@ export declare interface LiveGenerationConfig {
      * "How are you today?", the model may transcribe that output across three messages, broken up as "How a", "re yo", "u today?".
      */
     outputAudioTranscription?: AudioTranscriptionConfig;
+    /**
+     * The context window compression configuration.
+     *
+     * @beta
+     */
+    contextWindowCompression?: ContextWindowCompressionConfig;
 }
 
+/**
+ * The Live Generation Config.
+ *
+ * The public API ({@link LiveGenerationConfig}) has `inputAudioTranscription` and `outputAudioTranscription`,
+ * but the server expects these fields to be in the top-level `setup` message. This was a conscious API decision.
+ */
+declare type _LiveGenerationConfig = Omit<LiveGenerationConfig, 'inputAudioTranscription' | 'outputAudioTranscription'>;
+
 /**
  * Class for Live generative model APIs. The Live API enables low-latency, two-way multimodal
  * interactions with Gemini.
@@ -2395,9 +2643,10 @@ export declare interface LiveGenerationConfig {
  */
 export declare class LiveGenerativeModel extends AIModel {
     /**
+     * For testing injection
      * @internal
      */
-    private _webSocketHandler;
+    private _webSocketHandler?;
     generationConfig: LiveGenerationConfig;
     tools?: Tool[];
     toolConfig?: ToolConfig;
@@ -2407,9 +2656,10 @@ export declare class LiveGenerativeModel extends AIModel {
      */
     constructor(ai: AI, modelParams: LiveModelParams, 
     /**
+     * For testing injection
      * @internal
      */
-    _webSocketHandler: WebSocketHandler);
+    _webSocketHandler?: WebSocketHandler | undefined);
     /**
      * Starts a {@link LiveSession}.
      *
@@ -2418,7 +2668,7 @@ export declare class LiveGenerativeModel extends AIModel {
      *
      * @beta
      */
-    connect(): Promise<LiveSession>;
+    connect(sessionResumption?: SessionResumptionConfig): Promise<LiveSession>;
 }
 
 /**
@@ -2443,6 +2693,7 @@ export declare const LiveResponseType: {
     TOOL_CALL: string;
     TOOL_CALL_CANCELLATION: string;
     GOING_AWAY_NOTICE: string;
+    SESSION_RESUMPTION_UPDATE: string;
 };
 
 /**
@@ -2532,8 +2783,9 @@ export declare interface LiveServerToolCallCancellation {
  * @beta
  */
 export declare class LiveSession {
-    private webSocketHandler;
-    private serverMessages;
+    private _setupMessage;
+    private _apiSettings;
+    private _sessionResumption?;
     /**
      * Indicates whether this Live session is closed.
      *
@@ -2547,9 +2799,41 @@ export declare class LiveSession {
      */
     inConversation: boolean;
     /**
+     * Allows external code to await the opening of the WebSocket connection.
+     */
+    connectionPromise: Promise<void>;
+    /**
+     * Generator yielding WebSocket messages from the server.
+     */
+    private _serverMessages;
+    /**
+     * WebSocket handler. Injectable for testing.
+     */
+    private _webSocketHandler;
+    /**
+     * @internal
+     */
+    constructor(_setupMessage: _LiveClientSetup, _apiSettings: ApiSettings, _sessionResumption?: SessionResumptionConfig | undefined, webSocketHandler?: WebSocketHandler);
+    /**
+     * Initializes connection to the WebSocket. Should be called immediately
+     * after instantiation.
+     *
      * @internal
      */
-    constructor(webSocketHandler: WebSocketHandler, serverMessages: AsyncGenerator<unknown>);
+    private _connectSession;
+    /**
+     * Resumes an existing live session with the server.
+     *
+     * This closes the current WebSocket connection and establishes a new one using
+     * the same configuration (URI, headers, model, system instruction, tools, etc.)
+     * as the original session.
+     *
+     * @param sessionResumption - The configuration for session resumption, such as the handle to the previous session state to restore.
+     * @throws If the session resumption configuration is unsupported.
+     *
+     * @beta
+     */
+    resumeSession(sessionResumption?: SessionResumptionConfig): Promise<void>;
     /**
      * Sends content to the server.
      *
@@ -2629,7 +2913,7 @@ export declare class LiveSession {
      *
      * @beta
      */
-    receive(): AsyncGenerator<LiveServerContent | LiveServerToolCall | LiveServerToolCallCancellation | LiveServerGoingAwayNotice>;
+    receive(): AsyncGenerator<LiveServerContent | LiveServerToolCall | LiveServerToolCallCancellation | LiveServerGoingAwayNotice | LiveSessionResumptionUpdate>;
     /**
      * Closes this session.
      * All methods on this session will throw an error once this resolves.
@@ -2661,6 +2945,30 @@ export declare class LiveSession {
     sendMediaStream(mediaChunkStream: ReadableStream<GenerativeContentBlob>): Promise<void>;
 }
 
+/**
+ * An update of the session resumption state.
+ *
+ * This message is only sent if {@link SessionResumptionConfig} was set in the
+ * session setup.
+ *
+ * @beta
+ */
+export declare interface LiveSessionResumptionUpdate {
+    type: 'sessionResumptionUpdate';
+    /**
+     * The new handle that represents the state that can be resumed. Empty if `resumable` is false.
+     */
+    newHandle?: string;
+    /**
+     * Indicates if the session can be resumed at this point.
+     */
+    resumable?: boolean;
+    /**
+     * The index of the last client message that is included in the state represented by this update.
+     */
+    lastConsumedClientMessageIndex?: number;
+}
+
 /**
  * Content part modality.
  * @public
@@ -2894,6 +3202,21 @@ export declare const ResponseModality: {
  */
 export declare type ResponseModality = (typeof ResponseModality)[keyof typeof ResponseModality];
 
+/**
+ * Configuration options for data retrieval tools.
+ * @public
+ */
+export declare interface RetrievalConfig {
+    /**
+     * The location of the user.
+     */
+    latLng?: LatLng;
+    /**
+     * The language code of the user.
+     */
+    languageCode?: string;
+}
+
 /**
  * @public
  */
@@ -3193,7 +3516,7 @@ export declare interface Segment {
     /**
      * The zero-based start index of the segment within the specified `Part`,
      * measured in UTF-8 bytes. This offset is inclusive, starting from 0 at the
-     * beginning of the part's content (e.g., `Part.text`).
+     * beginning of the part's content (for example, `Part.text`).
      */
     startIndex: number;
     /**
@@ -3208,6 +3531,24 @@ export declare interface Segment {
     text: string;
 }
 
+/**
+ * Configuration for the session resumption mechanism.
+ *
+ * @remarks
+ * When included in the session setup, the server will send
+ * {@link LiveSessionResumptionUpdate} messages in the response stream.
+ *
+ * @beta
+ */
+export declare interface SessionResumptionConfig {
+    /**
+     * The session resumption handle of the previous session to restore.
+     *
+     * If not present, a new session will be started.
+     */
+    handle?: string;
+}
+
 /**
  * Options that can be provided per-request.
  * Extends the base {@link RequestOptions} (like `timeout` and `baseUrl`)
@@ -3249,6 +3590,25 @@ export declare interface SingleRequestOptions extends RequestOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * Configures the sliding window context compression mechanism.
+ *
+ * @remarks
+ * The sliding window discards content at the beginning of the
+ * context window. The resulting context will always begin at
+ * the start of a `user` role turn. System instructions
+ * will always remain at the start of the result.
+ *
+ * @beta
+ */
+export declare interface SlidingWindow {
+    /**
+     * The session reduction target, for example, how many tokens the model
+     * should keep.
+     */
+    targetTokens?: number;
+}
+
 /**
  * Configures speech synthesis.
  *
@@ -3495,10 +3855,12 @@ export declare class TemplateGenerativeModel {
      * @param templateId - The ID of the server-side template to execute.
      * @param templateVariables - A key-value map of variables to populate the
      * template with.
+     * @param singleRequestOptions - Optional. Options to use for this request.
+     * @param templateToolConfig - Optional. Configuration for tools to use with this request.
      *
      * @beta
      */
-    generateContent(templateId: string, templateVariables: Record<string, unknown>, singleRequestOptions?: SingleRequestOptions): Promise<GenerateContentResult>;
+    generateContent(templateId: string, templateVariables: Record<string, unknown>, singleRequestOptions?: SingleRequestOptions, templateToolConfig?: TemplateToolConfig): Promise<GenerateContentResult>;
     /**
      * Makes a single streaming call to the model and returns an object
      * containing an iterable stream that iterates over all chunks in the
@@ -3508,10 +3870,12 @@ export declare class TemplateGenerativeModel {
      * @param templateId - The ID of the server-side template to execute.
      * @param templateVariables - A key-value map of variables to populate the
      * template with.
+     * @param singleRequestOptions - Optional.Options to use for this request.
+     * @param templateToolConfig - Optional. Configuration for tools to use with this request.
      *
      * @beta
      */
-    generateContentStream(templateId: string, templateVariables: Record<string, unknown>, singleRequestOptions?: SingleRequestOptions): Promise<GenerateContentStreamResult>;
+    generateContentStream(templateId: string, templateVariables: Record<string, unknown>, singleRequestOptions?: SingleRequestOptions, templateToolConfig?: TemplateToolConfig): Promise<GenerateContentStreamResult>;
     /**
      * Starts a {@link TemplateChatSession} that will use this template to
      * respond to messages.
@@ -3576,6 +3940,15 @@ export declare interface TemplateRequestInternal extends Omit<TemplateGenerateCo
  */
 export declare type TemplateTool = TemplateFunctionDeclarationsTool;
 
+/**
+ * Tool configuration for `TemplateGenerativeModel`s.
+ * This config is shared for all tools provided in the server prompt template request.
+ * @public
+ */
+export declare interface TemplateToolConfig {
+    retrievalConfig?: RetrievalConfig;
+}
+
 /**
  * Content part interface if the part represents a text string.
  * @public
@@ -3680,7 +4053,7 @@ export declare type ThinkingLevel = (typeof ThinkingLevel)[keyof typeof Thinking
  * Defines a tool that model can call to access external knowledge.
  * @public
  */
-export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
+export declare type Tool = FunctionDeclarationsTool | GoogleMapsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 
 /**
  * Tool config. This config is shared for all tools provided in the request.
@@ -3688,6 +4061,7 @@ export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExe
  */
 export declare interface ToolConfig {
     functionCallingConfig?: FunctionCallingConfig;
+    retrievalConfig?: RetrievalConfig;
 }
 
 /**