@firebase/ai 2.11.1 → 2.12.0-20260505164105

package/dist/esm/src/methods/live-session.d.ts

@@ -14,8 +14,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { FunctionResponse, GenerativeContentBlob, LiveServerContent, LiveServerGoingAwayNotice, LiveServerToolCall, LiveServerToolCallCancellation, Part } from '../public-types';
+import { FunctionResponse, GenerativeContentBlob, LiveServerContent, LiveServerGoingAwayNotice, LiveServerToolCall, LiveServerToolCallCancellation, LiveSessionResumptionUpdate, Part, SessionResumptionConfig } from '../public-types';
 import { WebSocketHandler } from '../websocket';
+import { _LiveClientSetup } from '../types/live-responses';
+import { ApiSettings } from '../types/internal';
 /**
  * Represents an active, real-time, bidirectional conversation with the model.
  *
@@ -24,8 +26,9 @@ import { WebSocketHandler } from '../websocket';
  * @beta
  */
 export declare class LiveSession {
-    private webSocketHandler;
-    private serverMessages;
+    private _setupMessage;
+    private _apiSettings;
+    private _sessionResumption?;
     /**
      * Indicates whether this Live session is closed.
      *
@@ -39,9 +42,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.
      *
@@ -121,7 +156,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.

package/dist/esm/src/models/live-generative-model.d.ts

@@ -16,7 +16,7 @@
  */
 import { AIModel } from './ai-model';
 import { LiveSession } from '../methods/live-session';
-import { AI, Content, LiveGenerationConfig, LiveModelParams, Tool, ToolConfig } from '../public-types';
+import { AI, Content, LiveGenerationConfig, LiveModelParams, SessionResumptionConfig, Tool, ToolConfig } from '../public-types';
 import { WebSocketHandler } from '../websocket';
 /**
  * Class for Live generative model APIs. The Live API enables low-latency, two-way multimodal
@@ -28,9 +28,10 @@ import { WebSocketHandler } from '../websocket';
  */
 export declare class LiveGenerativeModel extends AIModel {
     /**
+     * For testing injection
      * @internal
      */
-    private _webSocketHandler;
+    private _webSocketHandler?;
     generationConfig: LiveGenerationConfig;
     tools?: Tool[];
     toolConfig?: ToolConfig;
@@ -40,9 +41,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}.
      *
@@ -51,5 +53,5 @@ export declare class LiveGenerativeModel extends AIModel {
      *
      * @beta
      */
-    connect(): Promise<LiveSession>;
+    connect(sessionResumption?: SessionResumptionConfig): Promise<LiveSession>;
 }

package/dist/esm/src/models/template-generative-model.d.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 import { GenerateContentResult, RequestOptions } from '../types';
-import { AI, GenerateContentStreamResult, SingleRequestOptions, StartTemplateChatParams, TemplateChatSession } from '../public-types';
+import { AI, GenerateContentStreamResult, SingleRequestOptions, StartTemplateChatParams, TemplateChatSession, TemplateToolConfig } from '../public-types';
 import { ApiSettings } from '../types/internal';
 /**
  * {@link GenerativeModel} APIs that execute on a server-side template.
@@ -44,10 +44,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
@@ -57,10 +59,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.

package/dist/esm/src/types/enums.d.ts

@@ -221,12 +221,92 @@ 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";
 };
 /**
  * Reason that a candidate finished.
  * @public
  */
 export type FinishReason = (typeof FinishReason)[keyof typeof FinishReason];
+/**
+ * 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 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 type ImageConfigImageSize = (typeof ImageConfigImageSize)[keyof typeof ImageConfigImageSize];
 /**
  * @public
  */

package/dist/esm/src/types/live-responses.d.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 import { Content, FunctionResponse, GenerativeContentBlob, Part } from './content';
-import { AudioTranscriptionConfig, LiveGenerationConfig, Tool, ToolConfig } from './requests';
+import { AudioTranscriptionConfig, ContextWindowCompressionConfig, LiveGenerationConfig, SessionResumptionConfig, Tool, ToolConfig } from './requests';
 import { Transcription } from './responses';
 /**
  * User input that is sent to the model.
@@ -68,6 +68,8 @@ export interface _LiveClientSetup {
         systemInstruction?: string | Part | Content;
         inputAudioTranscription?: AudioTranscriptionConfig;
         outputAudioTranscription?: AudioTranscriptionConfig;
+        sessionResumption?: SessionResumptionConfig;
+        contextWindowCompression?: ContextWindowCompressionConfig;
     };
 }
 /**

package/dist/esm/src/types/requests.d.ts

@@ -17,7 +17,7 @@
 import { ObjectSchema, TypedSchema } from '../requests/schema-builder';
 import { Content, Part } from './content';
 import { LanguageModelCreateOptions, LanguageModelPromptOptions } from './language-model';
-import { FunctionCallingMode, HarmBlockMethod, HarmBlockThreshold, HarmCategory, InferenceMode, ResponseModality, ThinkingLevel } from './enums';
+import { FunctionCallingMode, HarmBlockMethod, HarmBlockThreshold, HarmCategory, ImageConfigAspectRatio, ImageConfigImageSize, InferenceMode, ResponseModality, ThinkingLevel } from './enums';
 import { ObjectSchemaRequest, SchemaRequest } from './schema';
 /**
  * Base parameters for a number of methods.
@@ -92,6 +92,20 @@ export interface SafetySetting {
      */
     method?: HarmBlockMethod;
 }
+/**
+ * Configuration options for generating images with Gemini models.
+ * @public
+ */
+export interface ImageConfig {
+    /**
+     * The aspect ratio of generated images.
+     */
+    aspectRatio?: ImageConfigAspectRatio;
+    /**
+     * The size of the generated images.
+     */
+    imageSize?: ImageConfigImageSize;
+}
 /**
  * Config options for content-related requests
  * @public
@@ -145,6 +159,11 @@ export interface GenerationConfig {
      * Configuration for "thinking" behavior of compatible Gemini models.
      */
     thinkingConfig?: ThinkingConfig;
+    /**
+     * Configuration options for generating images with Gemini models.
+     * @public
+     */
+    imageConfig?: ImageConfig;
 }
 /**
  * Configuration parameters used by {@link LiveGenerativeModel} to control live content generation.
@@ -213,6 +232,66 @@ export 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;
+}
+/**
+ * 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 interface SlidingWindow {
+    /**
+     * The session reduction target, for example, how many tokens the model
+     * should keep.
+     */
+    targetTokens?: number;
+}
+/**
+ * Enables context window compression to manage the model's context window.
+ *
+ * @remarks
+ * This mechanism prevents the context from exceeding a given length.
+ *
+ * @beta
+ */
+export 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;
+}
+/**
+ * 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 interface SessionResumptionConfig {
+    /**
+     * The session resumption handle of the previous session to restore.
+     *
+     * If not present, a new session will be started.
+     */
+    handle?: string;
 }
 /**
  * Params for {@link GenerativeModel.startChat}.
@@ -328,7 +407,7 @@ export interface SingleRequestOptions extends RequestOptions {
  * Defines a tool that model can call to access external knowledge.
  * @public
  */
-export type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
+export type Tool = FunctionDeclarationsTool | GoogleMapsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 /**
  * Structured representation of a function declaration as defined by the
  * {@link https://spec.openapis.org/oas/v3.0.3 | OpenAPI 3.0 specification}.
@@ -385,6 +464,28 @@ export interface GoogleSearchTool {
      */
     googleSearch: GoogleSearch;
 }
+/**
+ * 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 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;
+}
 /**
  * A tool that enables the model to use code execution.
  *
@@ -405,6 +506,14 @@ export interface CodeExecutionTool {
  */
 export interface GoogleSearch {
 }
+/**
+ * Specifies the Google Maps configuration.
+ *
+ * @public
+ */
+export interface GoogleMaps {
+    enableWidget?: boolean;
+}
 /**
  * A tool that allows you to provide additional context to the models in the form of public web
  * URLs. By including URLs in your request, the Gemini model will access the content from those
@@ -444,6 +553,20 @@ export interface FunctionDeclarationsTool {
      */
     functionDeclarations?: FunctionDeclaration[];
 }
+/**
+ * An object that represents a latitude/longitude pair.
+ * @public
+ */
+export 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;
+}
 /**
  * Structured representation of a template function declaration.
  * Included in this declaration are the function name and parameters. This
@@ -516,6 +639,15 @@ export type TemplateTool = TemplateFunctionDeclarationsTool;
  */
 export interface ToolConfig {
     functionCallingConfig?: FunctionCallingConfig;
+    retrievalConfig?: RetrievalConfig;
+}
+/**
+ * Tool configuration for `TemplateGenerativeModel`s.
+ * This config is shared for all tools provided in the server prompt template request.
+ * @public
+ */
+export interface TemplateToolConfig {
+    retrievalConfig?: RetrievalConfig;
 }
 /**
  * @public
@@ -524,6 +656,20 @@ export interface FunctionCallingConfig {
     mode?: FunctionCallingMode;
     allowedFunctionNames?: string[];
 }
+/**
+ * Configuration options for data retrieval tools.
+ * @public
+ */
+export interface RetrievalConfig {
+    /**
+     * The location of the user.
+     */
+    latLng?: LatLng;
+    /**
+     * The language code of the user.
+     */
+    languageCode?: string;
+}
 /**
  * Encapsulates configuration for on-device inference.
  *

package/dist/esm/src/types/responses.d.ts

@@ -203,13 +203,19 @@ export interface Citation {
 /**
  * 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 interface GroundingMetadata {
@@ -238,6 +244,12 @@ export 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;
 }
 /**
  * Google search entry point.
@@ -273,6 +285,10 @@ export 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;
 }
 /**
  * A grounding chunk from the web.
@@ -300,6 +316,33 @@ export interface WebGroundingChunk {
      */
     domain?: string;
 }
+/**
+ * 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 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;
+}
 /**
  * Provides information about how a specific segment of the model's response is supported by the
  * retrieved grounding chunks.
@@ -336,7 +379,7 @@ export 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;
     /**
@@ -586,6 +629,29 @@ export interface LiveServerGoingAwayNotice {
      */
     timeLeft: number;
 }
+/**
+ * An update of the session resumption state.
+ *
+ * This message is only sent if {@link SessionResumptionConfig} was set in the
+ * session setup.
+ *
+ * @beta
+ */
+export 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;
+}
 /**
  * The types of responses that can be returned by {@link LiveSession.receive}.
  *
@@ -596,6 +662,7 @@ export declare const LiveResponseType: {
     TOOL_CALL: string;
     TOOL_CALL_CANCELLATION: string;
     GOING_AWAY_NOTICE: string;
+    SESSION_RESUMPTION_UPDATE: string;
 };
 /**
  * The types of responses that can be returned by {@link LiveSession.receive}.