@firebase/ai 1.4.0 → 1.4.1-canary.25b60fdaa

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

@@ -78,6 +78,10 @@ export interface GenerateContentResponse {
 export interface UsageMetadata {
     promptTokenCount: number;
     candidatesTokenCount: number;
+    /**
+     * The number of tokens used by the model's internal "thinking" process.
+     */
+    thoughtsTokenCount?: number;
     totalTokenCount: number;
     promptTokensDetails?: ModalityTokenCount[];
     candidatesTokensDetails?: ModalityTokenCount[];
@@ -151,34 +155,154 @@ export interface Citation {
     publicationDate?: Date;
 }
 /**
- * Metadata returned to client when grounding is enabled.
+ * Metadata returned when grounding is enabled.
+ *
+ * Currently, only Grounding with Google Search is supported (see {@link GoogleSearchTool}).
+ *
+ * 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).
+ *
  * @public
  */
 export 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”.
+     */
+    searchEntryPoint?: SearchEntrypoint;
+    /**
+     * A list of {@link GroundingChunk} objects. Each chunk represents a piece of retrieved content
+     * (for example, from a web page). that the model used to ground its response.
+     */
+    groundingChunks?: GroundingChunk[];
+    /**
+     * A list of {@link GroundingSupport} objects. Each object details how specific segments of the
+     * model's response are supported by the `groundingChunks`.
+     */
+    groundingSupports?: GroundingSupport[];
+    /**
+     * A list of web search queries that the model performed to gather the grounding information.
+     * These can be used to allow users to explore the search results themselves.
+     */
     webSearchQueries?: string[];
+    /**
+     * @deprecated Use {@link GroundingSupport} instead.
+     */
     retrievalQueries?: string[];
+}
+/**
+ * Google search entry point.
+ *
+ * @public
+ */
+export interface SearchEntrypoint {
     /**
-     * @deprecated
+     * HTML/CSS snippet that must be embedded in a web page. The snippet is designed to avoid
+     * undesired interaction with the rest of the page's CSS.
+     *
+     * To ensure proper rendering and prevent CSS conflicts, it is recommended
+     * to encapsulate this `renderedContent` within a shadow DOM when embedding it
+     * into a webpage. See {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM | MDN: Using shadow DOM}.
+     *
+     * @example
+     * ```javascript
+     * const container = document.createElement('div');
+     * document.body.appendChild(container);
+     * container.attachShadow({ mode: 'open' }).innerHTML = renderedContent;
+     * ```
      */
-    groundingAttributions: GroundingAttribution[];
+    renderedContent?: string;
 }
 /**
- * @deprecated
+ * Represents a chunk of retrieved data that supports a claim in the model's response. This is part
+ * of the grounding information provided when grounding is enabled.
+ *
  * @public
  */
-export interface GroundingAttribution {
-    segment: Segment;
-    confidenceScore?: number;
-    web?: WebAttribution;
-    retrievedContext?: RetrievedContextAttribution;
+export interface GroundingChunk {
+    /**
+     * Contains details if the grounding chunk is from a web source.
+     */
+    web?: WebGroundingChunk;
 }
 /**
+ * A grounding chunk from the web.
+ *
+ * Important: If using Grounding with Google Search, you are required to comply with the
+ * {@link https://cloud.google.com/terms/service-terms | Service Specific Terms} for "Grounding with Google Search".
+ *
+ * @public
+ */
+export interface WebGroundingChunk {
+    /**
+     * The URI of the retrieved web page.
+     */
+    uri?: string;
+    /**
+     * The title of the retrieved web page.
+     */
+    title?: string;
+    /**
+     * The domain of the original URI from which the content was retrieved.
+     *
+     * This property is only supported in the Vertex AI Gemini API ({@link VertexAIBackend}).
+     * When using the Gemini Developer API ({@link GoogleAIBackend}), this property will be
+     * `undefined`.
+     */
+    domain?: string;
+}
+/**
+ * Provides information about how a specific segment of the model's response is supported by the
+ * retrieved grounding chunks.
+ *
+ * @public
+ */
+export interface GroundingSupport {
+    /**
+     * Specifies the segment of the model's response content that this grounding support pertains to.
+     */
+    segment?: Segment;
+    /**
+     * A list of indices that refer to specific {@link GroundingChunk} objects within the
+     * {@link GroundingMetadata.groundingChunks} array. These referenced chunks
+     * are the sources that support the claim made in the associated `segment` of the response.
+     * For example, an array `[1, 3, 4]` means that `groundingChunks[1]`, `groundingChunks[3]`,
+     * and `groundingChunks[4]` are the retrieved content supporting this part of the response.
+     */
+    groundingChunkIndices?: number[];
+}
+/**
+ * Represents a specific segment within a {@link Content} object, often used to
+ * pinpoint the exact location of text or data that grounding information refers to.
+ *
  * @public
  */
 export interface Segment {
+    /**
+     * The zero-based index of the {@link Part} object within the `parts` array
+     * of its parent {@link Content} object. This identifies which part of the
+     * content the segment belongs to.
+     */
     partIndex: number;
+    /**
+     * 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`).
+     */
     startIndex: number;
+    /**
+     * The zero-based end index of the segment within the specified `Part`,
+     * measured in UTF-8 bytes. This offset is exclusive, meaning the character
+     * at this index is not included in the segment.
+     */
     endIndex: number;
+    /**
+     * The text corresponding to the segment from the response.
+     */
+    text: string;
 }
 /**
  * @public
@@ -243,11 +367,10 @@ export interface CountTokensResponse {
      */
     totalTokens: number;
     /**
+     * @deprecated Use `totalTokens` instead. This property is undefined when using models greater than `gemini-1.5-*`.
+     *
      * The total number of billable characters counted across all instances
      * from the request.
-     *
-     * This property is only supported when using the Vertex AI Gemini API ({@link VertexAIBackend}).
-     * When using the Gemini Developer API ({@link GoogleAIBackend}), this property is not supported and will default to 0.
      */
     totalBillableCharacters?: number;
     /**

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

@@ -20,26 +20,39 @@
  * {@link https://swagger.io/docs/specification/data-models/data-types/ | OpenAPI specification}
  * @public
  */
-export declare enum SchemaType {
+export declare const SchemaType: {
     /** String type. */
-    STRING = "string",
+    readonly STRING: "string";
     /** Number type. */
-    NUMBER = "number",
+    readonly NUMBER: "number";
     /** Integer type. */
-    INTEGER = "integer",
+    readonly INTEGER: "integer";
     /** Boolean type. */
-    BOOLEAN = "boolean",
+    readonly BOOLEAN: "boolean";
     /** Array type. */
-    ARRAY = "array",
+    readonly ARRAY: "array";
     /** Object type. */
-    OBJECT = "object"
-}
+    readonly OBJECT: "object";
+};
+/**
+ * Contains the list of OpenAPI data types
+ * as defined by the
+ * {@link https://swagger.io/docs/specification/data-models/data-types/ | OpenAPI specification}
+ * @public
+ */
+export type SchemaType = (typeof SchemaType)[keyof typeof SchemaType];
 /**
  * Basic {@link Schema} properties shared across several Schema-related
  * types.
  * @public
  */
 export interface SchemaShared<T> {
+    /**
+     * An array of {@link Schema}. The generated data must be valid against any of the schemas
+     * listed in this array. This allows specifying multiple possible structures or types for a
+     * single field.
+     */
+    anyOf?: T[];
     /** Optional. The format of the property.
      * When using the Gemini Developer API ({@link GoogleAIBackend}), this must be either `'enum'` or
      * `'date-time'`, otherwise requests will fail.
@@ -55,9 +68,9 @@ export interface SchemaShared<T> {
     title?: string;
     /** Optional. The items of the property. */
     items?: T;
-    /** The minimum number of items (elements) in a schema of type {@link SchemaType.ARRAY}. */
+    /** The minimum number of items (elements) in a schema of {@link (SchemaType:type)} `array`. */
     minItems?: number;
-    /** The maximum number of items (elements) in a schema of type {@link SchemaType.ARRAY}. */
+    /** The maximum number of items (elements) in a schema of {@link (SchemaType:type)} `array`. */
     maxItems?: number;
     /** Optional. Map of `Schema` objects. */
     properties?: {
@@ -90,10 +103,10 @@ export interface SchemaParams extends SchemaShared<SchemaInterface> {
  */
 export interface SchemaRequest extends SchemaShared<SchemaRequest> {
     /**
-     * The type of the property. {@link
-     * SchemaType}.
+     * The type of the property. this can only be undefined when using `anyOf` schemas,
+     * which do not have an explicit type in the {@link https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type | OpenAPI specification }.
      */
-    type: SchemaType;
+    type?: SchemaType;
     /** Optional. Array of required property. */
     required?: string[];
 }
@@ -103,16 +116,24 @@ export interface SchemaRequest extends SchemaShared<SchemaRequest> {
  */
 export interface SchemaInterface extends SchemaShared<SchemaInterface> {
     /**
-     * The type of the property. {@link
-     * SchemaType}.
+     * The type of the property. this can only be undefined when using `anyof` schemas,
+     * which do not have an explicit type in the {@link https://swagger.io/docs/specification/v3_0/data-models/data-types/#any-type | OpenAPI Specification}.
      */
-    type: SchemaType;
+    type?: SchemaType;
 }
 /**
- * Interface for {@link ObjectSchema} class.
+ * Interface for JSON parameters in a schema of {@link SchemaType}
+ * "object" when not using the `Schema.object()` helper.
  * @public
  */
-export interface ObjectSchemaInterface extends SchemaInterface {
-    type: SchemaType.OBJECT;
-    optionalProperties?: string[];
+export interface ObjectSchemaRequest extends SchemaRequest {
+    type: 'object';
+    /**
+     * This is not a property accepted in the final request to the backend, but is
+     * a client-side convenience property that is only usable by constructing
+     * a schema through the `Schema.object()` helper method. Populating this
+     * property will cause response errors if the object is not wrapped with
+     * `Schema.object()`.
+     */
+    optionalProperties?: never;
 }