Merge branch 'main' into add_interrupt_support

Author: VinayGuthal

.github/workflows/dataconnect.yml

@@ -34,7 +34,7 @@ env:
   FDC_JAVA_VERSION: ${{ inputs.javaVersion || '17' }}
   FDC_ANDROID_EMULATOR_API_LEVEL: ${{ inputs.androidEmulatorApiLevel || '34' }}
   FDC_NODEJS_VERSION: ${{ inputs.nodeJsVersion || '20' }}
-  FDC_FIREBASE_TOOLS_VERSION: ${{ inputs.firebaseToolsVersion || '14.15.1' }}
+  FDC_FIREBASE_TOOLS_VERSION: ${{ inputs.firebaseToolsVersion || '14.18.0' }}
   FDC_FIREBASE_TOOLS_DIR: /tmp/firebase-tools
   FDC_FIREBASE_COMMAND: /tmp/firebase-tools/node_modules/.bin/firebase
   FDC_PYTHON_VERSION: ${{ inputs.pythonVersion || '3.13' }}

.github/workflows/dataconnect_demo_app.yml

@@ -18,7 +18,7 @@ on:
 
 env:
   FDC_NODE_VERSION: ${{ inputs.nodeVersion || '20' }}
-  FDC_FIREBASE_TOOLS_VERSION: ${{ inputs.firebaseToolsVersion || '14.15.1' }}
+  FDC_FIREBASE_TOOLS_VERSION: ${{ inputs.firebaseToolsVersion || '14.18.0' }}
   FDC_JAVA_VERSION: ${{ inputs.javaVersion || '17' }}
   FDC_FIREBASE_TOOLS_DIR: ${{ github.workspace }}/firebase-tools
   FDC_FIREBASE_COMMAND: ${{ github.workspace }}/firebase-tools/node_modules/.bin/firebase

build.gradle.kts

@@ -62,7 +62,7 @@ fun Project.applySpotless() {
     }
     format("styling") {
       target("src/**/*.md", "*.md", "docs/**/*.md")
-      targetExclude("**/third_party/**", "src/test/resources/**")
+      targetExclude("**/third_party/**", "src/test/resources/**", "release_report.md")
       prettier().config(mapOf("printWidth" to 100, "proseWrap" to "always"))
     }
   }

firebase-ai/CHANGELOG.md

@@ -1,9 +1,14 @@
 # Unreleased
 
 - [changed] **Breaking Change**: Removed the `candidateCount` option from `LiveGenerationConfig`
-- [changed] Added better error messages to `ServiceConnectionHandshakeFailedException`
 - [changed] Added support for user interrupts for the `startAudioConversation` method in the
   `LiveSession` class.
+- [changed] Added support for the URL context tool, which allows the model to access content from
+  provided public web URLs to inform and enhance its responses. (#7382)
+- [changed] Added better error messages to `ServiceConnectionHandshakeFailedException` (#7412)
+- [changed] Marked the public constructor for `UsageMetadata` as deprecated (#7420)
+- [changed] Using Firebase AI Logic with the Gemini Developer API is now Generally Available (GA).
+- [changed] Using Firebase AI Logic with the Imagen generation APIs is now Generally Available (GA).
 
 # 17.3.0
 
@@ -47,7 +52,7 @@
 
 - [feature] Added support for configuring the "thinking" budget when using Gemini 2.5 series models.
   (#6990)
-- [feature] **Breaking Change**: Add support for Grounding with Google Search (#7042).
+- [feature] **Breaking Change**: Add support for grounding with Google Search (#7042).
   - **Action Required:** Update all references of `groundingAttributions`, `webSearchQueries`,
     `retrievalQueries` in `GroundingMetadata` to be non-optional.
 - [changed] require at least one argument for `generateContent()`, `generateContentStream()` and

firebase-ai/api.txt

@@ -170,7 +170,6 @@ internal constructor(
    * @return The initialized [ImagenModel] instance.
    */
   @JvmOverloads
-  @PublicPreviewAPI
   public fun imagenModel(
     modelName: String,
     generationConfig: ImagenGenerationConfig? = null,

firebase-ai/src/main/kotlin/com/google/firebase/ai/FirebaseAI.kt

@@ -45,7 +45,6 @@ import com.google.firebase.auth.internal.InternalAuthProvider
  * See the documentation for a list of
  * [supported models](https://firebase.google.com/docs/ai-logic/models).
  */
-@PublicPreviewAPI
 public class ImagenModel
 internal constructor(
   private val modelName: String,
@@ -106,6 +105,7 @@ internal constructor(
    * @param prompt the text input given to the model as a prompt
    * @param config the editing configuration settings
    */
+  @PublicPreviewAPI
   public suspend fun editImage(
     referenceImages: List<ImagenReferenceImage>,
     prompt: String,
@@ -130,6 +130,7 @@ internal constructor(
    * @param mask the mask which defines where in the image can be painted by Imagen.
    * @param config the editing configuration settings, it should include an [ImagenEditMode]
    */
+  @PublicPreviewAPI
   public suspend fun inpaintImage(
     image: ImagenInlineImage,
     prompt: String,
@@ -154,6 +155,7 @@ internal constructor(
    * @param config the editing configuration settings
    * @see [ImagenMaskReference.generateMaskAndPadForOutpainting]
    */
+  @PublicPreviewAPI
   public suspend fun outpaintImage(
     image: ImagenInlineImage,
     newDimensions: Dimensions,
@@ -172,6 +174,7 @@ internal constructor(
     prompt: String,
     generationConfig: ImagenGenerationConfig? = null,
   ): GenerateImageRequest {
+    @OptIn(PublicPreviewAPI::class)
     return GenerateImageRequest(
       listOf(GenerateImageRequest.ImagenPrompt(prompt, null)),
       GenerateImageRequest.ImagenParameters(
@@ -191,6 +194,7 @@ internal constructor(
     )
   }
 
+  @PublicPreviewAPI
   private fun constructEditRequest(
     referenceImages: List<ImagenReferenceImage>,
     prompt: String,

firebase-ai/src/main/kotlin/com/google/firebase/ai/ImagenModel.kt

@@ -77,7 +77,7 @@ internal data class CountTokensRequest(
 }
 
 @Serializable
-@PublicPreviewAPI
+@OptIn(PublicPreviewAPI::class)
 internal data class GenerateImageRequest(
   val instances: List<ImagenPrompt>,
   val parameters: ImagenParameters,
@@ -88,7 +88,6 @@ internal data class GenerateImageRequest(
     val referenceImages: List<ImagenReferenceImage.Internal>?
   )
 
-  @OptIn(PublicPreviewAPI::class)
   @Serializable
   internal data class ImagenParameters(
     val sampleCount: Int,
@@ -102,7 +101,7 @@ internal data class GenerateImageRequest(
     val addWatermark: Boolean?,
     val imageOutputOptions: ImagenImageFormat.Internal?,
     val editMode: String?,
-    val editConfig: ImagenEditingConfig.Internal?,
+    @OptIn(PublicPreviewAPI::class) val editConfig: ImagenEditingConfig.Internal?,
   )
 
   @Serializable

firebase-ai/src/main/kotlin/com/google/firebase/ai/common/Request.kt

@@ -33,37 +33,47 @@ import kotlinx.serialization.json.JsonNames
  * @property safetyRatings A list of [SafetyRating]s describing the generated content.
  * @property citationMetadata Metadata about the sources used to generate this content.
  * @property finishReason The reason the model stopped generating content, if it exist.
- * @property groundingMetadata Metadata returned to the client when grounding is enabled.
+ * @property groundingMetadata Metadata returned to the client when the model grounds its response.
+ * @property urlContextMetadata Metadata returned to the client when the [UrlContext] tool is
+ * enabled.
  */
 public class Candidate
+@OptIn(PublicPreviewAPI::class)
 internal constructor(
   public val content: Content,
   public val safetyRatings: List<SafetyRating>,
   public val citationMetadata: CitationMetadata?,
   public val finishReason: FinishReason?,
-  public val groundingMetadata: GroundingMetadata?
+  public val groundingMetadata: GroundingMetadata?,
+  @property:PublicPreviewAPI public val urlContextMetadata: UrlContextMetadata?
 ) {
 
+  @OptIn(PublicPreviewAPI::class)
   @Serializable
   internal data class Internal(
     val content: Content.Internal? = null,
     val finishReason: FinishReason.Internal? = null,
     val safetyRatings: List<SafetyRating.Internal>? = null,
     val citationMetadata: CitationMetadata.Internal? = null,
-    val groundingMetadata: GroundingMetadata.Internal? = null
+    val groundingMetadata: GroundingMetadata.Internal? = null,
+    val urlContextMetadata: UrlContextMetadata.Internal? = null
   ) {
+
+    @OptIn(PublicPreviewAPI::class)
     internal fun toPublic(): Candidate {
       val safetyRatings = safetyRatings?.mapNotNull { it.toPublic() }.orEmpty()
       val citations = citationMetadata?.toPublic()
       val finishReason = finishReason?.toPublic()
       val groundingMetadata = groundingMetadata?.toPublic()
+      val urlContextMetadata = urlContextMetadata?.toPublic()
 
       return Candidate(
         this.content?.toPublic() ?: content("model") {},
         safetyRatings,
         citations,
         finishReason,
-        groundingMetadata
+        groundingMetadata,
+        urlContextMetadata
       )
     }
   }
@@ -297,7 +307,7 @@ public class FinishReason private constructor(public val name: String, public va
 /**
  * Metadata returned to the client when grounding is enabled.
  *
- * If using Grounding with Google Search, you are required to comply with the "Grounding with Google
+ * If using grounding with Google Search, you are required to comply with the "Grounding with Google
  * Search" usage requirements for your chosen API provider:
  * [Gemini Developer API](https://ai.google.dev/gemini-api/terms#grounding-with-google-search) or
  * Vertex AI Gemini API (see [Service Terms](https://cloud.google.com/terms/service-terms) section
@@ -372,8 +382,7 @@ public class SearchEntryPoint(
 }
 
 /**
- * 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.
+ * Represents a chunk of retrieved data that supports a claim in the model's response.
  *
  * @property web Contains details if the grounding chunk is from a web source.
  */
@@ -492,3 +501,87 @@ public class Segment(
       )
   }
 }
+
+/**
+ * Metadata related to the [UrlContext] tool.
+ *
+ * @property urlMetadata List of [UrlMetadata] used to provide context to the Gemini model.
+ */
+@PublicPreviewAPI
+public class UrlContextMetadata internal constructor(public val urlMetadata: List<UrlMetadata>) {
+
+  @Serializable
+  @PublicPreviewAPI
+  internal data class Internal(val urlMetadata: List<UrlMetadata.Internal>?) {
+    internal fun toPublic() = UrlContextMetadata(urlMetadata?.map { it.toPublic() } ?: emptyList())
+  }
+}
+
+/**
+ * Metadata for a single URL retrieved by the [UrlContext] tool.
+ *
+ * @property retrievedUrl The retrieved URL.
+ * @property urlRetrievalStatus The status of the URL retrieval.
+ */
+@PublicPreviewAPI
+public class UrlMetadata
+internal constructor(
+  public val retrievedUrl: String?,
+  public val urlRetrievalStatus: UrlRetrievalStatus
+) {
+  @Serializable
+  internal data class Internal(
+    val retrievedUrl: String?,
+    val urlRetrievalStatus: UrlRetrievalStatus.Internal
+  ) {
+    internal fun toPublic() = UrlMetadata(retrievedUrl, urlRetrievalStatus.toPublic())
+  }
+}
+
+/**
+ * The status of a URL retrieval.
+ *
+ * @property name The name of the retrieval status.
+ * @property ordinal The ordinal value of the retrieval status.
+ */
+@PublicPreviewAPI
+public class UrlRetrievalStatus
+private constructor(public val name: String, public val ordinal: Int) {
+
+  @Serializable(Internal.Serializer::class)
+  internal enum class Internal {
+    @SerialName("URL_RETRIEVAL_STATUS_UNSPECIFIED") UNSPECIFIED,
+    @SerialName("URL_RETRIEVAL_STATUS_SUCCESS") SUCCESS,
+    @SerialName("URL_RETRIEVAL_STATUS_ERROR") ERROR,
+    @SerialName("URL_RETRIEVAL_STATUS_PAYWALL") PAYWALL,
+    @SerialName("URL_RETRIEVAL_STATUS_UNSAFE") UNSAFE;
+
+    internal object Serializer : KSerializer<Internal> by FirstOrdinalSerializer(Internal::class)
+
+    internal fun toPublic() =
+      when (this) {
+        SUCCESS -> UrlRetrievalStatus.SUCCESS
+        ERROR -> UrlRetrievalStatus.ERROR
+        PAYWALL -> UrlRetrievalStatus.PAYWALL
+        UNSAFE -> UrlRetrievalStatus.UNSAFE
+        else -> UrlRetrievalStatus.UNSPECIFIED
+      }
+  }
+
+  public companion object {
+    /** Unspecified retrieval status. */
+    @JvmField public val UNSPECIFIED: UrlRetrievalStatus = UrlRetrievalStatus("UNSPECIFIED", 0)
+
+    /** The URL retrieval was successful. */
+    @JvmField public val SUCCESS: UrlRetrievalStatus = UrlRetrievalStatus("SUCCESS", 1)
+
+    /** The URL retrieval failed. */
+    @JvmField public val ERROR: UrlRetrievalStatus = UrlRetrievalStatus("ERROR", 2)
+
+    /** The URL retrieval failed because the content is behind a paywall. */
+    @JvmField public val PAYWALL: UrlRetrievalStatus = UrlRetrievalStatus("PAYWALL", 3)
+
+    /** The URL retrieval failed because the content is unsafe. */
+    @JvmField public val UNSAFE: UrlRetrievalStatus = UrlRetrievalStatus("UNSAFE", 4)
+  }
+}

firebase-ai/src/main/kotlin/com/google/firebase/ai/type/Candidate.kt

@@ -22,7 +22,7 @@ import kotlinx.serialization.Serializable
  * A tool that allows the generative model to connect to Google Search to access and incorporate
  * up-to-date information from the web into its responses.
  *
- * When using this feature, you are required to comply with the "Grounding with Google Search" usage
+ * When using this feature, you are required to comply with the "grounding with Google Search" usage
  * requirements for your chosen API provider:
  * [Gemini Developer API](https://ai.google.dev/gemini-api/terms#grounding-with-google-search) or
  * Vertex AI Gemini API (see [Service Terms](https://cloud.google.com/terms/service-terms) section