Add missing construction to TemplateTool that is present in Tool (#8188)

`TemplateTool` is separate from `Tool` for some reason and was missing
various features that are supported on `Tool` and work correctly with
templates. This adds them to `TemplateTool` and adds testing to validate
the maps grounding behavior on Google AI. Vertex does not respond
correctly to our grounding query at the moment so has not been included.

Author: emilypgoogle

ai-logic/firebase-ai/CHANGELOG.md

@@ -1,5 +1,6 @@
 # Unreleased
 
+- [feature] Added the `retrievalConfig` argument to `TemplateToolConfig` (#8107)
 - [fixed] Fixed citation indices to be native UTF-16 instead of UTF-8. (#8056)
 
 # 17.12.0

ai-logic/firebase-ai/api.txt

@@ -213,8 +213,8 @@ package com.google.firebase.ai {
     method @com.google.firebase.ai.type.PublicPreviewAPI public com.google.firebase.ai.TemplateChat startChat(String templateId, java.util.Map<java.lang.String,?> inputs, java.util.List<com.google.firebase.ai.type.Content> history = emptyList());
   }
 
-  @com.google.firebase.ai.type.PublicPreviewAPI public final class TemplateImagenModel {
-    method public suspend Object? generateImages(String templateId, java.util.Map<java.lang.String,?> inputs, kotlin.coroutines.Continuation<? super com.google.firebase.ai.type.ImagenGenerationResponse<com.google.firebase.ai.type.ImagenInlineImage>>);
+  @Deprecated @com.google.firebase.ai.type.PublicPreviewAPI public final class TemplateImagenModel {
+    method @Deprecated public suspend Object? generateImages(String templateId, java.util.Map<java.lang.String,?> inputs, kotlin.coroutines.Continuation<? super com.google.firebase.ai.type.ImagenGenerationResponse<com.google.firebase.ai.type.ImagenInlineImage>>);
   }
 
 }
@@ -1839,15 +1839,20 @@ package com.google.firebase.ai.type {
 
   public final class TemplateTool {
     method public static com.google.firebase.ai.type.TemplateTool functionDeclarations(java.util.List<? extends com.google.firebase.ai.type.TemplateFunctionDeclaration> functionDeclarations, java.util.List<? extends com.google.firebase.ai.type.TemplateAutoFunctionDeclaration<? extends java.lang.Object?,? extends java.lang.Object?>>? autoFunctionDeclarations = null);
+    method public static com.google.firebase.ai.type.TemplateTool googleMaps();
+    method public static com.google.firebase.ai.type.TemplateTool googleMaps(com.google.firebase.ai.type.GoogleMaps googleMaps = com.google.firebase.ai.type.GoogleMaps());
     field public static final com.google.firebase.ai.type.TemplateTool.Companion Companion;
   }
 
   public static final class TemplateTool.Companion {
     method public com.google.firebase.ai.type.TemplateTool functionDeclarations(java.util.List<? extends com.google.firebase.ai.type.TemplateFunctionDeclaration> functionDeclarations, java.util.List<? extends com.google.firebase.ai.type.TemplateAutoFunctionDeclaration<? extends java.lang.Object?,? extends java.lang.Object?>>? autoFunctionDeclarations = null);
+    method public com.google.firebase.ai.type.TemplateTool googleMaps();
+    method public com.google.firebase.ai.type.TemplateTool googleMaps(com.google.firebase.ai.type.GoogleMaps googleMaps = com.google.firebase.ai.type.GoogleMaps());
   }
 
   public final class TemplateToolConfig {
     ctor public TemplateToolConfig();
+    ctor public TemplateToolConfig(com.google.firebase.ai.type.RetrievalConfig? retrievalConfig);
   }
 
   public final class TextPart implements com.google.firebase.ai.type.Part {

ai-logic/firebase-ai/gradle.properties

@@ -12,5 +12,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-version=17.12.1
+version=17.13.0
 latestReleasedVersion=17.12.0

ai-logic/firebase-ai/src/androidTest/kotlin/com/google/firebase/ai/TemplateIntegrationTests.kt

@@ -16,9 +16,16 @@
 
 package com.google.firebase.ai
 
+import com.google.firebase.ai.type.GenerativeBackend
+import com.google.firebase.ai.type.LatLng
 import com.google.firebase.ai.type.PublicPreviewAPI
+import com.google.firebase.ai.type.RetrievalConfig
+import com.google.firebase.ai.type.TemplateTool
+import com.google.firebase.ai.type.TemplateToolConfig
 import io.kotest.matchers.collections.shouldNotBeEmpty
+import io.kotest.matchers.string.shouldContain
 import io.kotest.matchers.string.shouldContainIgnoringCase
+import io.kotest.matchers.string.shouldNotContain
 import kotlinx.coroutines.flow.toList
 import kotlinx.coroutines.runBlocking
 import org.junit.Before
@@ -102,4 +109,49 @@ class TemplateIntegrationTests {
         it shouldContainIgnoringCase topic
       }
   }
+
+  @Test
+  fun testTemplateGroundingCity_googleAI(): Unit = runBlocking {
+    val model =
+      FirebaseAI.getInstance(AIModels.app(), GenerativeBackend.googleAI())
+        .templateGenerativeModel(
+          tools = listOf(TemplateTool.googleMaps()),
+          toolConfig =
+            TemplateToolConfig(
+              RetrievalConfig(
+                latLng = LatLng(latitude = 30.2672, longitude = -97.7431),
+                languageCode = "en_US",
+              )
+            )
+        )
+    val responses =
+      model
+        .generateContentStream("maps-test-template-google-ai", mapOf("landmark" to "city"))
+        .toList()
+    responses
+      .joinToString { it.text ?: "" }
+      .lowercase()
+      .replace(",", "")
+      .replace("  ", " ") // Model sometimes doubles spacing
+      .let { it shouldContainIgnoringCase "new york" }
+  }
+
+  @Test
+  fun testTemplateToolsUrlContext_googleAI(): Unit = runBlocking {
+    val model =
+      FirebaseAI.getInstance(AIModels.app(), GenerativeBackend.googleAI())
+        .templateGenerativeModel(
+          tools = listOf(), // URLContext not provided, still can read links
+        )
+    val response =
+      model.generateContent(
+        "url-context-test-template-google-ai",
+        mapOf(
+          "url" to "https://en.wikipedia.org/wiki/Kasane_Teto",
+          "question" to "What is the given name of the linked individual?",
+        )
+      )
+    response.text?.lowercase() shouldContain "teto"
+    response.text?.lowercase() shouldNotContain "kasane"
+  }
 }

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

@@ -16,17 +16,19 @@
 
 package com.google.firebase.ai.type
 
+import kotlinx.serialization.InternalSerializationApi
 import kotlinx.serialization.Serializable
 
 /**
  * Contains a set of tools (like function declarations) that the server template model has access
  * to.
  */
 public class TemplateTool
-@OptIn(PublicPreviewAPI::class)
+@OptIn(PublicPreviewAPI::class, InternalSerializationApi::class)
 internal constructor(
   internal val functionDeclarations: List<TemplateFunctionDeclaration>?,
   internal val autoFunctionDeclarations: List<TemplateAutoFunctionDeclaration<*, *>>? = null,
+  internal val googleMaps: GoogleMaps?,
 ) {
 
   @OptIn(PublicPreviewAPI::class)
@@ -36,11 +38,13 @@ internal constructor(
         functionDeclarations?.let { addAll(it.map { it.toInternal() }) }
         autoFunctionDeclarations?.let { addAll(it.map { it.toInternal() }) }
       },
+      googleMaps?.toInternal(),
     )
 
   @Serializable
   internal data class Internal(
     val templateFunctions: List<TemplateFunctionDeclaration.Internal>? = null,
+    val googleMaps: GoogleMaps.Internal? = null,
   )
 
   public companion object {
@@ -56,7 +60,27 @@ internal constructor(
       functionDeclarations: List<TemplateFunctionDeclaration>,
       autoFunctionDeclarations: List<TemplateAutoFunctionDeclaration<*, *>>? = null,
     ): TemplateTool {
-      return TemplateTool(functionDeclarations, autoFunctionDeclarations)
+      return TemplateTool(functionDeclarations, autoFunctionDeclarations, null)
+    }
+
+    /**
+     * Creates a [TemplateTool] instance that allows the model to use grounding with Google Maps.
+     *
+     * Grounding with Google Maps can be used to allow the model to connect to Google Maps to
+     * incorporate location-based information into its responses.
+     *
+     * When using this feature, you are required to comply with the "Grounding with Google Maps"
+     * usage requirements for your chosen API provider:
+     * [Gemini Developer API](https://ai.google.dev/gemini-api/terms#grounding-with-google-maps) or
+     * Vertex AI Gemini API (see [Service Terms](https://cloud.google.com/terms/service-terms)
+     * section within the Service Specific Terms).
+     *
+     * @return A [TemplateTool] configured for Google Maps.
+     */
+    @JvmStatic
+    @JvmOverloads
+    public fun googleMaps(googleMaps: GoogleMaps = GoogleMaps()): TemplateTool {
+      return TemplateTool(null, null, googleMaps)
     }
   }
 }
@@ -127,8 +151,13 @@ internal constructor(
 }
 
 /** Config for template tools to use with server prompts. */
-public class TemplateToolConfig {
-  internal fun toInternal(): ToolConfig.Internal? {
-    return null // Empty config payload as defined in flutter API
+public class TemplateToolConfig public constructor(private val retrievalConfig: RetrievalConfig?) {
+
+  public constructor() : this(null)
+  internal fun toInternal(): ToolConfig.Internal {
+    return ToolConfig.Internal(
+      functionCallingConfig = null,
+      retrievalConfig = retrievalConfig?.toInternal()
+    )
   }
 }

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

@@ -61,7 +61,7 @@ internal constructor(
   public companion object {
 
     @OptIn(PublicPreviewAPI::class)
-    private val codeExecutionInstance by lazy {
+    internal val codeExecutionInstance by lazy {
       Tool(null, null, null, JsonObject(emptyMap()), null, null)
     }
 
@@ -118,7 +118,7 @@ internal constructor(
      * Creates a [Tool] instance that allows the model to use grounding with Google Search.
      *
      * Grounding with Google Search can be used to allow the model to connect to Google Search to
-     * access and incorporate up-to-date information from the web into it's responses.
+     * 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 requirements for your chosen API provider: