Add documentation snippets to the repo

generativeai-android-sample/app/build.gradle.kts

@@ -37,6 +37,10 @@ android {
         }
     }
 
+    sourceSets.getByName("main") {
+        java.setSrcDirs(listOf("src/main/java", "src/main/kotlin", "../../samples/src/main/java"))
+    }
+
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_1_8
         targetCompatibility = JavaVersion.VERSION_1_8
@@ -59,6 +63,12 @@ dependencies {
     implementation("androidx.activity:activity-compose:1.8.1")
     implementation("androidx.navigation:navigation-compose:2.7.5")
 
+    // Required for one-shot operations (to use `ListenableFuture` from Guava Android)
+    implementation("com.google.guava:guava:31.0.1-android")
+
+    // Required for streaming operations (to use `Publisher` from Reactive Streams)
+    implementation("org.reactivestreams:reactive-streams:1.0.4")
+
     implementation(platform("androidx.compose:compose-bom:2023.10.01"))
     implementation("androidx.compose.ui:ui")
     implementation("androidx.compose.ui:ui-graphics")

samples/DEVELOPING.md

@@ -0,0 +1,27 @@
+# Developing
+
+The snippets in this directory are organized to simplify their use as documentation.
+
+## Snippets requirements
+
+All snippets must compile.
+
+## Workflow
+
+1. In Android Studio, import the `generativeai-android-sample` project
+2. In the left-hand bar, using the "Android" prespective, you'll
+   notice that the within the `app` module, there are two packages:
+   - `com.google.ai.client.generative.samples` which contains the snippets
+   - `com.google.ai.sample` which contains the actual quickstart app
+3. Make all necessary changes to the code in the
+   `com.google.ai.client.generative.samples` snippets
+4. To compile the snippets, compile the `app` module itself.
+
+**IMPORTANT:** Always add both the Kotlin and the Java versions of the
+snippets at the same time to maintain parity.
+
+### How does it work
+
+Under the hood, the configuration of the app module, in
+`generativeai-android-sample/build.gradle.kts`, has been modified to
+include in the main `sourceSet` the code for the samples.

samples/README.md

@@ -0,0 +1 @@
+GenerativeAI sample snippets for Android in Kotlin and Java

samples/src/main/java/com/google/ai/client/generative/samples/BuildConfig.java

@@ -0,0 +1,22 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.ai.client.generative.samples;
+
+// This file was manually created for testing purposes only.
+// For instructions on how to generate this file automatically, see the section
+// "Set up your API Key" in https://ai.google.dev/gemini-api/docs/quickstart?lang=android
+public class BuildConfig {
+    public static String apiKey = "invalidApiKey";
+}

samples/src/main/java/com/google/ai/client/generative/samples/chat.kt

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.ai.client.generative.samples
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import com.google.ai.client.generativeai.GenerativeModel
+import com.google.ai.client.generativeai.type.content
+import com.google.ai.sample.R
+
+suspend fun chat() {
+  // [START chat]
+  val generativeModel =
+      GenerativeModel(
+          // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
+          modelName = "gemini-1.5-flash",
+          // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+          apiKey = BuildConfig.apiKey)
+
+  val chat =
+      generativeModel.startChat(
+          history =
+              listOf(
+                  content(role = "user") { text("Hello, I have 2 dogs in my house.") },
+                  content(role = "model") {
+                    text("Great to meet you. What would you like to know?")
+                  }))
+
+  val response = chat.sendMessage("How many paws are in my house?")
+  print(response.text)
+  // [END chat]
+}
+
+suspend fun chatStreaming() {
+  // [START chat_streaming]
+  // Use streaming with multi-turn conversations (like chat)
+  val generativeModel =
+      GenerativeModel(
+          // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
+          modelName = "gemini-1.5-flash",
+          // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+          apiKey = BuildConfig.apiKey)
+
+  val chat =
+      generativeModel.startChat(
+          history =
+              listOf(
+                  content(role = "user") { text("Hello, I have 2 dogs in my house.") },
+                  content(role = "model") {
+                    text("Great to meet you. What would you like to know?")
+                  }))
+
+  chat.sendMessageStream("How many paws are in my house?").collect { chunk -> print(chunk.text) }
+  // [END chat_streaming]
+}
+
+suspend fun chatStreamingWithImages(context: Context) {
+  // [START chat_with-images_streaming]
+  // Use streaming with multi-turn conversations (like chat)
+  val generativeModel =
+      GenerativeModel(
+          // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
+          modelName = "gemini-1.5-flash",
+          // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+          apiKey = BuildConfig.apiKey)
+
+  val chat =
+      generativeModel.startChat(
+          history =
+              listOf(
+                  content(role = "user") { text("Hello, I have 2 dogs in my house.") },
+                  content(role = "model") {
+                    text("Great to meet you. What would you like to know?")
+                  }))
+
+  val image: Bitmap = BitmapFactory.decodeResource(context.resources, R.drawable.image)
+
+  val inputContent = content {
+    image(image)
+    text("This is a picture of them, what breed are they?")
+  }
+
+  chat.sendMessageStream(inputContent).collect { chunk -> print(chunk.text) }
+  // [END chat_with-images_streaming]
+}

samples/src/main/java/com/google/ai/client/generative/samples/controlled_generation.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.ai.client.generative.samples
+
+// TODO

samples/src/main/java/com/google/ai/client/generative/samples/count_tokens.kt

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.ai.client.generative.samples
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import com.google.ai.client.generativeai.GenerativeModel
+import com.google.ai.client.generativeai.type.content
+import com.google.ai.sample.R
+
+suspend fun tokensTextOnly() {
+  // [START tokens_text-only]
+  val generativeModel =
+      GenerativeModel(
+          // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
+          modelName = "gemini-1.5-flash",
+          // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+          apiKey = BuildConfig.apiKey)
+
+  // For text-only input
+  val (totalTokens) = generativeModel.countTokens("Write a story about a magic backpack.")
+  print(totalTokens)
+  // [END tokens_text-only]
+}
+
+suspend fun tokensChat() {
+  // [START tokens_chat]
+  val generativeModel =
+      GenerativeModel(
+          // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
+          modelName = "gemini-1.5-flash",
+          // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+          apiKey = BuildConfig.apiKey)
+
+  val chat =
+      generativeModel.startChat(
+          history =
+              listOf(
+                  content(role = "user") { text("Hello, I have 2 dogs in my house.") },
+                  content(role = "model") {
+                    text("Great to meet you. What would you like to know?")
+                  }))
+
+  val history = chat.history
+  val messageContent = content { text("This is the message I intend to send") }
+  val (totalTokens) = generativeModel.countTokens(*history.toTypedArray(), messageContent)
+  print(totalTokens)
+  // [END tokens_chat]
+}
+
+suspend fun tokensMultimodalImageInline(context: Context) {
+  // [START tokens_multimodal-image_inline]
+  val generativeModel =
+      GenerativeModel(
+          // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
+          modelName = "gemini-1.5-flash",
+          // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+          apiKey = BuildConfig.apiKey)
+
+  val image1: Bitmap = BitmapFactory.decodeResource(context.resources, R.drawable.image1)
+  val image2: Bitmap = BitmapFactory.decodeResource(context.resources, R.drawable.image2)
+
+  val multiModalContent = content {
+    image(image1)
+    image(image2)
+    text("What's the difference between these pictures?")
+  }
+
+  val (totalTokens) = generativeModel.countTokens(multiModalContent)
+  print(totalTokens)
+  // [START tokens_multimodal-image_inline]
+}

samples/src/main/java/com/google/ai/client/generative/samples/function_calling.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.ai.client.generative.samples
+
+// TODO

samples/src/main/java/com/google/ai/client/generative/samples/java/BuildConfig.java

@@ -0,0 +1,22 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.ai.client.generative.samples.java;
+
+// This file was manually created for testing purposes only.
+// For instructions on how to generate this file automatically, see the section
+// "Set up your API Key" in https://ai.google.dev/gemini-api/docs/quickstart?lang=android
+public class BuildConfig {
+  public static String apiKey = "invalidApiKey";
+}