Add documentation snippets to the repo (#182)

Internal b/346393026

---------

Co-authored-by: rachelsaunders <52258509+rachelsaunders@users.noreply.github.com>
Co-authored-by: David Motsonashvili <davidmotson@gmail.com>
Co-authored-by: David Motsonashvili <davidmotson@google.com>

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

@@ -37,6 +37,16 @@ android {
         }
     }
 
+    buildTypes {
+        create("samples") {
+            initWith(getByName("debug"))
+        }
+    }
+
+    sourceSets.getByName("samples") {
+        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 +69,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,107 @@
+/*
+ * 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
+
+// Set up your API Key
+// ====================
+//
+// To use the Gemini API, you'll need an API key. To learn more, see
+// the "Set up your API Key section" in the [Gemini API
+// quickstart](https://ai.google.dev/gemini-api/docs/quickstart?lang=android#set-up-api-key).
+
+suspend fun chat() {
+  // [START chat]
+  val generativeModel =
+      GenerativeModel(
+          // Specify a Gemini model appropriate for your use case
+          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(
+          // Specify a Gemini model appropriate for your use case
+          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_streaming_with_images]
+  // Use streaming with multi-turn conversations (like chat)
+  val generativeModel =
+      GenerativeModel(
+          // Specify a Gemini model appropriate for your use case
+          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_streaming_with_images]
+}

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

@@ -0,0 +1,63 @@
+/*
+ * 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 com.google.ai.client.generativeai.GenerativeModel
+import com.google.ai.client.generativeai.type.Tool
+
+// Set up your API Key
+// ====================
+//
+// To use the Gemini API, you'll need an API key. To learn more, see
+// the "Set up your API Key section" in the [Gemini API
+// quickstart](https://ai.google.dev/gemini-api/docs/quickstart?lang=android#set-up-api-key).
+
+suspend fun codeExecutionBasic() {
+    // [START code_execution_basic]
+
+    val model = GenerativeModel(
+        // Specify a Gemini model appropriate for your use case
+        modelName = "gemini-1.5-pro",
+        // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+        apiKey = BuildConfig.apiKey,
+        tools = listOf(Tool.CODE_EXECUTION)
+    )
+
+    val response = model.generateContent("What is the sum of the first 50 prime numbers?")
+
+    println(response.text)
+    // [END code_execution_basic]
+}
+
+suspend fun codeExecutionChat() {
+    // [START code_execution_chat]
+
+    val model = GenerativeModel(
+        // Specify a Gemini model appropriate for your use case
+        modelName = "gemini-1.5-pro",
+        // Access your API key as a Build Configuration variable (see "Set up your API key" above)
+        apiKey = BuildConfig.apiKey,
+        tools = listOf(Tool.CODE_EXECUTION)
+    )
+
+    val chat = model.startChat()
+
+    val response = chat.sendMessage("What is the sum of the first 50 prime numbers?")
+
+    println(response.text)
+    // [END code_execution_chat]
+}

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

@@ -0,0 +1,50 @@
+/*
+ * 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 com.google.ai.client.generativeai.GenerativeModel
+import com.google.ai.client.generativeai.type.generationConfig
+
+// Set up your API Key
+// ====================
+//
+// To use the Gemini API, you'll need an API key. To learn more, see
+// the "Set up your API Key section" in the [Gemini API
+// quickstart](https://ai.google.dev/gemini-api/docs/quickstart?lang=android#set-up-api-key).
+
+
+suspend fun configureModel() {
+  // [START configure_model_parameters]
+  val config = generationConfig {
+    temperature = 0.9f
+    topK = 16
+    topP = 0.1f
+    maxOutputTokens = 200
+    stopSequences = listOf("red")
+  }
+
+  val generativeModel =
+      GenerativeModel(
+          // Specify a Gemini model appropriate for your use case
+          modelName = "gemini-1.5-flash",
+          apiKey = BuildConfig.apiKey,
+          generationConfig = config)
+  // [END configure_model_parameters]
+
+  // Added to silence the compiler warning about unused variable.
+  print(generativeModel)
+}

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

@@ -0,0 +1,26 @@
+/*
+ * 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
+
+// Set up your API Key
+// ====================
+//
+// To use the Gemini API, you'll need an API key. To learn more, see
+// the "Set up your API Key section" in the [Gemini API
+// quickstart](https://ai.google.dev/gemini-api/docs/quickstart?lang=android#set-up-api-key).
+
+// TODO