@firebase/ai 2.2.1 → 2.3.0-caching-fdc.9f17eac6e

package/dist/ai.d.ts

@@ -366,13 +366,13 @@ export declare class ChatSession {
 }
 
 /**
- * <b>(EXPERIMENTAL)</b> Defines an inference "backend" that uses Chrome's on-device model,
+ * Defines an inference "backend" that uses Chrome's on-device model,
  * and encapsulates logic for detecting when on-device inference is
  * possible.
  *
  * These methods should not be called directly by the user.
  *
- * @public
+ * @beta
  */
 export declare interface ChromeAdapter {
     /**
@@ -436,6 +436,56 @@ export declare interface CitationMetadata {
     citations: Citation[];
 }
 
+/**
+ * The results of code execution run by the model.
+ *
+ * @beta
+ */
+export declare interface CodeExecutionResult {
+    /**
+     * The result of the code execution.
+     */
+    outcome?: Outcome;
+    /**
+     * The output from the code execution, or an error message
+     * if it failed.
+     */
+    output?: string;
+}
+
+/**
+ * Represents the code execution result from the model.
+ *
+ * @beta
+ */
+export declare interface CodeExecutionResultPart {
+    text?: never;
+    inlineData?: never;
+    functionCall?: never;
+    functionResponse?: never;
+    fileData: never;
+    thought?: never;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: CodeExecutionResult;
+}
+
+/**
+ * A tool that enables the model to use code execution.
+ *
+ * @beta
+ */
+export declare interface CodeExecutionTool {
+    /**
+     * Specifies the Google Search configuration.
+     * Currently, this is an empty object, but it's reserved for future configuration options.
+     */
+    codeExecution: {};
+}
+
 /**
  * Content type for both prompts and response candidates.
  * @public
@@ -573,6 +623,42 @@ export declare interface ErrorDetails {
     [key: string]: unknown;
 }
 
+/**
+ * An interface for executable code returned by the model.
+ *
+ * @beta
+ */
+export declare interface ExecutableCode {
+    /**
+     * The programming language of the code.
+     */
+    language?: Language;
+    /**
+     * The source code to be executed.
+     */
+    code?: string;
+}
+
+/**
+ * Represents the code that is executed by the model.
+ *
+ * @beta
+ */
+export declare interface ExecutableCodePart {
+    text?: never;
+    inlineData?: never;
+    functionCall?: never;
+    functionResponse?: never;
+    fileData: never;
+    thought?: never;
+    /**
+     * @internal
+     */
+    thoughtSignature?: never;
+    executableCode?: ExecutableCode;
+    codeExecutionResult?: never;
+}
+
 /**
  * Data pointing to a file uploaded on Google Cloud Storage.
  * @public
@@ -597,6 +683,8 @@ export declare interface FileDataPart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 
 /**
@@ -718,6 +806,8 @@ export declare interface FunctionCallPart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 
 /**
@@ -805,6 +895,8 @@ export declare interface FunctionResponsePart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 
 /**
@@ -819,6 +911,7 @@ export declare interface GenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: CitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 
 /**
@@ -1074,6 +1167,7 @@ export declare interface GoogleAIGenerateContentCandidate {
     safetyRatings?: SafetyRating[];
     citationMetadata?: GoogleAICitationMetadata;
     groundingMetadata?: GroundingMetadata;
+    urlContextMetadata?: URLContextMetadata;
 }
 
 /**
@@ -1110,8 +1204,6 @@ export declare interface GoogleSearchTool {
     /**
      * Specifies the Google Search configuration.
      * Currently, this is an empty object, but it's reserved for future configuration options.
-     * Specifies the Google Search configuration. Currently, this is an empty object, but it's
-     * reserved for future configuration options.
      *
      * When using this feature, 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}
@@ -1335,9 +1427,8 @@ export declare const HarmSeverity: {
 export declare type HarmSeverity = (typeof HarmSeverity)[keyof typeof HarmSeverity];
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Configures hybrid inference.
- * @public
+ * @beta
  */
 export declare interface HybridParams {
     /**
@@ -1820,20 +1911,37 @@ export declare interface ImagenSafetySettings {
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Determines whether inference happens on-device or in-cloud.
- * @public
+ *
+ * @remarks
+ * <b>PREFER_ON_DEVICE:</b> Attempt to make inference calls using an
+ * on-device model. If on-device inference is not available, the SDK
+ * will fall back to using a cloud-hosted model.
+ * <br/>
+ * <b>ONLY_ON_DEVICE:</b> Only attempt to make inference calls using an
+ * on-device model. The SDK will not fall back to a cloud-hosted model.
+ * If on-device inference is not available, inference methods will throw.
+ * <br/>
+ * <b>ONLY_IN_CLOUD:</b> Only attempt to make inference calls using a
+ * cloud-hosted model. The SDK will not fall back to an on-device model.
+ * <br/>
+ * <b>PREFER_IN_CLOUD:</b> Attempt to make inference calls to a
+ * cloud-hosted model. If not available, the SDK will fall back to an
+ * on-device model.
+ *
+ * @beta
  */
 export declare const InferenceMode: {
     readonly PREFER_ON_DEVICE: "prefer_on_device";
     readonly ONLY_ON_DEVICE: "only_on_device";
     readonly ONLY_IN_CLOUD: "only_in_cloud";
+    readonly PREFER_IN_CLOUD: "prefer_in_cloud";
 };
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Determines whether inference happens on-device or in-cloud.
- * @public
+ *
+ * @beta
  */
 export declare type InferenceMode = (typeof InferenceMode)[keyof typeof InferenceMode];
 
@@ -1855,6 +1963,8 @@ export declare interface InlineDataPart {
      * @internal
      */
     thoughtSignature?: never;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 
 /**
@@ -1866,9 +1976,25 @@ export declare class IntegerSchema extends Schema {
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
+ * The programming language of the code.
+ *
+ * @beta
+ */
+export declare const Language: {
+    UNSPECIFIED: string;
+    PYTHON: string;
+};
+
+/**
+ * The programming language of the code.
+ *
+ * @beta
+ */
+export declare type Language = (typeof Language)[keyof typeof Language];
+
+/**
  * Configures the creation of an on-device language model session.
- * @public
+ * @beta
  */
 export declare interface LanguageModelCreateCoreOptions {
     topK?: number;
@@ -1877,9 +2003,8 @@ export declare interface LanguageModelCreateCoreOptions {
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Configures the creation of an on-device language model session.
- * @public
+ * @beta
  */
 export declare interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
     signal?: AbortSignal;
@@ -1887,18 +2012,16 @@ export declare interface LanguageModelCreateOptions extends LanguageModelCreateC
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Options for the expected inputs for an on-device language model.
- * @public
+ * @beta
  */ export declare interface LanguageModelExpected {
     type: LanguageModelMessageType;
     languages?: string[];
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * An on-device language model message.
- * @public
+ * @beta
  */
 export declare interface LanguageModelMessage {
     role: LanguageModelMessageRole;
@@ -1906,9 +2029,8 @@ export declare interface LanguageModelMessage {
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * An on-device language model content object.
- * @public
+ * @beta
  */
 export declare interface LanguageModelMessageContent {
     type: LanguageModelMessageType;
@@ -1916,30 +2038,26 @@ export declare interface LanguageModelMessageContent {
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Content formats that can be provided as on-device message content.
- * @public
+ * @beta
  */
 export declare type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Allowable roles for on-device language model usage.
- * @public
+ * @beta
  */
 export declare type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Allowable types for on-device language model messages.
- * @public
+ * @beta
  */
 export declare type LanguageModelMessageType = 'text' | 'image' | 'audio';
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Options for an on-device language model prompt.
- * @public
+ * @beta
  */
 export declare interface LanguageModelPromptOptions {
     responseConstraint?: object;
@@ -2158,6 +2276,15 @@ export declare class LiveSession {
      * @beta
      */
     sendMediaChunks(mediaChunks: GenerativeContentBlob[]): Promise<void>;
+    /**
+     * Sends function responses to the server.
+     *
+     * @param functionResponses - The function responses to send.
+     * @throws If this session has been closed.
+     *
+     * @beta
+     */
+    sendFunctionResponses(functionResponses: FunctionResponse[]): Promise<void>;
     /**
      * Sends a stream of {@link GenerativeContentBlob}.
      *
@@ -2291,22 +2418,40 @@ export declare interface ObjectSchemaRequest extends SchemaRequest {
 }
 
 /**
- * <b>(EXPERIMENTAL)</b>
  * Encapsulates configuration for on-device inference.
  *
- * @public
+ * @beta
  */
 export declare interface OnDeviceParams {
     createOptions?: LanguageModelCreateOptions;
     promptOptions?: LanguageModelPromptOptions;
 }
 
+/**
+ * Represents the result of the code execution.
+ *
+ * @beta
+ */
+export declare const Outcome: {
+    UNSPECIFIED: string;
+    OK: string;
+    FAILED: string;
+    DEADLINE_EXCEEDED: string;
+};
+
+/**
+ * Represents the result of the code execution.
+ *
+ * @beta
+ */
+export declare type Outcome = (typeof Outcome)[keyof typeof Outcome];
+
 /**
  * Content part - includes text, image/video, or function call/response
  * part types.
  * @public
  */
-export declare type Part = TextPart | InlineDataPart | FunctionCallPart | FunctionResponsePart | FileDataPart;
+export declare type Part = TextPart | InlineDataPart | FunctionCallPart | FunctionResponsePart | FileDataPart | ExecutableCodePart | CodeExecutionResultPart;
 
 /**
  * Possible roles.
@@ -2777,7 +2922,7 @@ export declare interface StartAudioConversationOptions {
      * The handler should perform the function call and return the result as a `Part`,
      * which will then be sent back to the model.
      */
-    functionCallingHandler?: (functionCalls: LiveServerToolCall['functionCalls']) => Promise<Part>;
+    functionCallingHandler?: (functionCalls: FunctionCall[]) => Promise<FunctionResponse>;
 }
 
 /**
@@ -2819,6 +2964,8 @@ export declare interface TextPart {
      * @internal
      */
     thoughtSignature?: string;
+    executableCode?: never;
+    codeExecutionResult?: never;
 }
 
 /**
@@ -2859,7 +3006,7 @@ export declare interface ThinkingConfig {
  * Defines a tool that model can call to access external knowledge.
  * @public
  */
-export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool;
+export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool | CodeExecutionTool | URLContextTool;
 
 /**
  * Tool config. This config is shared for all tools provided in the request.
@@ -2875,6 +3022,115 @@ export declare interface ToolConfig {
  */
 export declare type TypedSchema = IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;
 
+/**
+ * Specifies the URL Context configuration.
+ *
+ * @beta
+ */
+export declare interface URLContext {
+}
+
+/**
+ * Metadata related to {@link URLContextTool}.
+ *
+ * @beta
+ */
+export declare interface URLContextMetadata {
+    /**
+     * List of URL metadata used to provide context to the Gemini model.
+     */
+    urlMetadata: URLMetadata[];
+}
+
+/**
+ * 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
+ * pages to inform and enhance its response.
+ *
+ * @beta
+ */
+export declare interface URLContextTool {
+    /**
+     * Specifies the URL Context configuration.
+     */
+    urlContext: URLContext;
+}
+
+/**
+ * Metadata for a single URL retrieved by the {@link URLContextTool} tool.
+ *
+ * @beta
+ */
+export declare interface URLMetadata {
+    /**
+     * The retrieved URL.
+     */
+    retrievedUrl?: string;
+    /**
+     * The status of the URL retrieval.
+     */
+    urlRetrievalStatus?: URLRetrievalStatus;
+}
+
+/**
+ * The status of a URL retrieval.
+ *
+ * @remarks
+ * <b>URL_RETRIEVAL_STATUS_UNSPECIFIED:</b> Unspecified retrieval status.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_UNSAFE:</b> The URL retrieval failed because the content is unsafe.
+ * <br/>
+ *
+ * @beta
+ */
+export declare const URLRetrievalStatus: {
+    /**
+     * Unspecified retrieval status.
+     */
+    URL_RETRIEVAL_STATUS_UNSPECIFIED: string;
+    /**
+     * The URL retrieval was successful.
+     */
+    URL_RETRIEVAL_STATUS_SUCCESS: string;
+    /**
+     * The URL retrieval failed.
+     */
+    URL_RETRIEVAL_STATUS_ERROR: string;
+    /**
+     * The URL retrieval failed because the content is behind a paywall.
+     */
+    URL_RETRIEVAL_STATUS_PAYWALL: string;
+    /**
+     * The URL retrieval failed because the content is unsafe.
+     */
+    URL_RETRIEVAL_STATUS_UNSAFE: string;
+};
+
+/**
+ * The status of a URL retrieval.
+ *
+ * @remarks
+ * <b>URL_RETRIEVAL_STATUS_UNSPECIFIED:</b> Unspecified retrieval status.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_SUCCESS:</b> The URL retrieval was successful.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_ERROR:</b> The URL retrieval failed.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_PAYWALL:</b> The URL retrieval failed because the content is behind a paywall.
+ * <br/>
+ * <b>URL_RETRIEVAL_STATUS_UNSAFE:</b> The URL retrieval failed because the content is unsafe.
+ * <br/>
+ *
+ * @beta
+ */
+export declare type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRetrievalStatus];
+
 /**
  * Usage metadata about a {@link GenerateContentResponse}.
  *
@@ -2888,8 +3144,16 @@ export declare interface UsageMetadata {
      */
     thoughtsTokenCount?: number;
     totalTokenCount: number;
+    /**
+     * The number of tokens used by tools.
+     */
+    toolUsePromptTokenCount?: number;
     promptTokensDetails?: ModalityTokenCount[];
     candidatesTokensDetails?: ModalityTokenCount[];
+    /**
+     * A list of tokens used by tools, broken down by modality.
+     */
+    toolUsePromptTokensDetails?: ModalityTokenCount[];
 }
 
 /**