@firebase/ai 2.0.0 → 2.1.0-canary.02280d747

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;
 }
 
 /**
@@ -315,12 +345,13 @@ export declare class BooleanSchema extends Schema {
  */
 export declare class ChatSession {
     model: string;
+    private chromeAdapter?;
     params?: StartChatParams | undefined;
     requestOptions?: RequestOptions | undefined;
     private _apiSettings;
     private _history;
     private _sendPromise;
-    constructor(apiSettings: ApiSettings, model: string, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
+    constructor(apiSettings: ApiSettings, model: string, chromeAdapter?: ChromeAdapter | undefined, params?: StartChatParams | undefined, requestOptions?: RequestOptions | undefined);
     /**
      * Gets the chat history so far. Blocked prompts are not added to history.
      * Neither blocked candidates nor the prompts that generated them are added
@@ -340,6 +371,46 @@ export declare class ChatSession {
     sendMessageStream(request: string | Array<string | Part>): Promise<GenerateContentStreamResult>;
 }
 
+/**
+ * <b>(EXPERIMENTAL)</b> 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
+ */
+export declare interface ChromeAdapter {
+    /**
+     * Checks if the on-device model is capable of handling a given
+     * request.
+     * @param request - A potential request to be passed to the model.
+     */
+    isAvailable(request: GenerateContentRequest): Promise<boolean>;
+    /**
+     * Generates content using on-device inference.
+     *
+     * @remarks
+     * This is comparable to {@link GenerativeModel.generateContent} for generating
+     * content using in-cloud inference.
+     * @param request - a standard Firebase AI {@link GenerateContentRequest}
+     */
+    generateContent(request: GenerateContentRequest): Promise<Response>;
+    /**
+     * Generates a content stream using on-device inference.
+     *
+     * @remarks
+     * This is comparable to {@link GenerativeModel.generateContentStream} for generating
+     * a content stream using in-cloud inference.
+     * @param request - a standard Firebase AI {@link GenerateContentRequest}
+     */
+    generateContentStream(request: GenerateContentRequest): Promise<Response>;
+    /**
+     * @internal
+     */
+    countTokens(request: CountTokensRequest): Promise<Response>;
+}
+
 /**
  * A single citation.
  * @public
@@ -489,6 +560,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
@@ -601,6 +674,9 @@ export declare const FunctionCallingMode: {
     readonly NONE: "NONE";
 };
 
+/**
+ * @public
+ */
 export declare type FunctionCallingMode = (typeof FunctionCallingMode)[keyof typeof FunctionCallingMode];
 
 /**
@@ -810,13 +886,14 @@ export declare interface GenerativeContentBlob {
  * @public
  */
 export declare class GenerativeModel extends AIModel {
+    private chromeAdapter?;
     generationConfig: GenerationConfig;
     safetySettings: SafetySetting[];
     requestOptions?: RequestOptions;
     tools?: Tool[];
     toolConfig?: ToolConfig;
     systemInstruction?: Content;
-    constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions);
+    constructor(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions, chromeAdapter?: ChromeAdapter | undefined);
     /**
      * Makes a single non-streaming call to the model
      * and returns an object containing a single {@link GenerateContentResponse}.
@@ -876,7 +953,7 @@ export declare function getAI(app?: FirebaseApp, options?: AIOptions): AI;
  *
  * @public
  */
-export declare function getGenerativeModel(ai: AI, modelParams: ModelParams, requestOptions?: RequestOptions): GenerativeModel;
+export declare function getGenerativeModel(ai: AI, modelParams: ModelParams | HybridParams, requestOptions?: RequestOptions): GenerativeModel;
 
 /**
  * Returns an {@link ImagenModel} class with methods for using Imagen.
@@ -1016,7 +1093,7 @@ export declare interface GroundingMetadata {
     /**
      * Google Search entry point for web searches. This contains an HTML/CSS snippet that must be
      * embedded in an app to display a Google Search entry point for follow-up web searches related to
-     * a model's “Grounded Response”.
+     * a model's "Grounded Response".
      */
     searchEntryPoint?: SearchEntrypoint;
     /**
@@ -1107,7 +1184,7 @@ export declare const HarmBlockThreshold: {
     readonly BLOCK_NONE: "BLOCK_NONE";
     /**
      * All content will be allowed. This is the same as `BLOCK_NONE`, but the metadata corresponding
-     * to the {@link HarmCategory} will not be present in the response.
+     * to the {@link (HarmCategory:type)} will not be present in the response.
      */
     readonly OFF: "OFF";
 };
@@ -1200,13 +1277,33 @@ export declare const HarmSeverity: {
  */
 export declare type HarmSeverity = (typeof HarmSeverity)[keyof typeof HarmSeverity];
 
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Configures hybrid inference.
+ * @public
+ */
+export declare interface HybridParams {
+    /**
+     * Specifies on-device or in-cloud inference. Defaults to prefer on-device.
+     */
+    mode: InferenceMode;
+    /**
+     * Optional. Specifies advanced params for on-device inference.
+     */
+    onDeviceParams?: OnDeviceParams;
+    /**
+     * Optional. Specifies advanced params for in-cloud inference.
+     */
+    inCloudParams?: ModelParams;
+}
+
 /**
  * Aspect ratios for Imagen images.
  *
  * To specify an aspect ratio for generated images, set the `aspectRatio` property in your
  * {@link ImagenGenerationConfig}.
  *
- * See the the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation }
+ * See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation }
  * for more details and examples of the supported aspect ratios.
  *
  * @beta
@@ -1240,7 +1337,7 @@ export declare const ImagenAspectRatio: {
  * To specify an aspect ratio for generated images, set the `aspectRatio` property in your
  * {@link ImagenGenerationConfig}.
  *
- * See the the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation }
+ * See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation }
  * for more details and examples of the supported aspect ratios.
  *
  * @beta
@@ -1251,6 +1348,7 @@ export declare type ImagenAspectRatio = (typeof ImagenAspectRatio)[keyof typeof
  * An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.
  *
  * This feature is not available yet.
+ * @beta
  */
 export declare interface ImagenGCSImage {
     /**
@@ -1664,6 +1762,24 @@ export declare interface ImagenSafetySettings {
     personFilterLevel?: ImagenPersonFilterLevel;
 }
 
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Determines whether inference happens on-device or in-cloud.
+ * @public
+ */
+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";
+};
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Determines whether inference happens on-device or in-cloud.
+ * @public
+ */
+export declare type InferenceMode = (typeof InferenceMode)[keyof typeof InferenceMode];
+
 /**
  * Content part interface if the part represents an image.
  * @public
@@ -1687,6 +1803,86 @@ export declare class IntegerSchema extends Schema {
     constructor(schemaParams?: SchemaParams);
 }
 
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Configures the creation of an on-device language model session.
+ * @public
+ */
+export declare interface LanguageModelCreateCoreOptions {
+    topK?: number;
+    temperature?: number;
+    expectedInputs?: LanguageModelExpected[];
+}
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Configures the creation of an on-device language model session.
+ * @public
+ */
+export declare interface LanguageModelCreateOptions extends LanguageModelCreateCoreOptions {
+    signal?: AbortSignal;
+    initialPrompts?: LanguageModelMessage[];
+}
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Options for the expected inputs for an on-device language model.
+ * @public
+ */ export declare interface LanguageModelExpected {
+    type: LanguageModelMessageType;
+    languages?: string[];
+}
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * An on-device language model message.
+ * @public
+ */
+export declare interface LanguageModelMessage {
+    role: LanguageModelMessageRole;
+    content: LanguageModelMessageContent[];
+}
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * An on-device language model content object.
+ * @public
+ */
+export declare interface LanguageModelMessageContent {
+    type: LanguageModelMessageType;
+    value: LanguageModelMessageContentValue;
+}
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Content formats that can be provided as on-device message content.
+ * @public
+ */
+export declare type LanguageModelMessageContentValue = ImageBitmapSource | AudioBuffer | BufferSource | string;
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Allowable roles for on-device language model usage.
+ * @public
+ */
+export declare type LanguageModelMessageRole = 'system' | 'user' | 'assistant';
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Allowable types for on-device language model messages.
+ * @public
+ */
+export declare type LanguageModelMessageType = 'text' | 'image' | 'audio';
+
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Options for an on-device language model prompt.
+ * @public
+ */
+export declare interface LanguageModelPromptOptions {
+    responseConstraint?: object;
+}
+
 /**
  * Content part modality.
  * @public
@@ -1775,7 +1971,7 @@ export declare class ObjectSchema extends Schema {
 }
 
 /**
- * Interface for JSON parameters in a schema of {@link SchemaType}
+ * Interface for JSON parameters in a schema of {@link (SchemaType:type)}
  * "object" when not using the `Schema.object()` helper.
  * @public
  */
@@ -1791,6 +1987,17 @@ export declare interface ObjectSchemaRequest extends SchemaRequest {
     optionalProperties?: never;
 }
 
+/**
+ * <b>(EXPERIMENTAL)</b>
+ * Encapsulates configuration for on-device inference.
+ *
+ * @public
+ */
+export declare interface OnDeviceParams {
+    createOptions?: LanguageModelCreateOptions;
+    promptOptions?: LanguageModelPromptOptions;
+}
+
 /**
  * Content part - includes text, image/video, or function call/response
  * part types.
@@ -1830,7 +2037,10 @@ export declare interface RequestOptions {
      */
     timeout?: number;
     /**
-     * Base url for endpoint. Defaults to https://firebasevertexai.googleapis.com
+     * Base url for endpoint. Defaults to
+     * https://firebasevertexai.googleapis.com, which is the
+     * {@link https://console.cloud.google.com/apis/library/firebasevertexai.googleapis.com?project=_ | Firebase AI Logic API}
+     * (used regardless of your chosen Gemini API provider).
      */
     baseUrl?: string;
 }