Kotlin: Add Bedrock Runtime invoke model example (#7221)

Co-authored-by: scmacdon <[email protected]>

Author: amasotti

.doc_gen/metadata/bedrock-runtime_metadata.yaml

@@ -673,6 +673,14 @@ bedrock-runtime_InvokeModel_TitanText:
             - description: Use the Invoke Model API to send a text message.
               snippet_tags:
                 - bedrock-runtime.java2.InvokeModel_AmazonTitanText
+    Kotlin:
+      versions:
+        - sdk_version: 1
+          github: kotlin/services/bedrock-runtime
+          excerpts:
+            - description: Use the Invoke Model API to generate a short story.
+              snippet_tags:
+                - bedrock-runtime.kotlin.InvokeModel_AmazonTitanText
     .NET:
       versions:
         - sdk_version: 3

kotlin/services/bedrock-runtime/README.md

@@ -0,0 +1,77 @@
+# Amazon Bedrock Runtime code examples for the SDK for Kotlin
+
+## Overview
+
+Shows how to use the AWS SDK for Kotlin to work with Amazon Bedrock Runtime.
+
+<!--custom.overview.start-->
+This section provides examples that show how to invoke foundation models using the Amazon Bedrock Runtime API with the AWS SDK for Kotlin.
+<!--custom.overview.end-->
+
+_Amazon Bedrock Runtime is a fully managed service that makes it easy to use foundation models from third-party providers and Amazon._
+
+## ⚠ Important
+
+* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/).
+* Running the tests might result in charges to your AWS account.
+* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
+<!--custom.important.start-->
+<!--custom.important.end-->
+
+## Code examples
+
+### Prerequisites
+
+For prerequisites, see the [README](../../README.md#Prerequisites) in the `kotlin` folder.
+
+
+<!--custom.prerequisites.start-->
+> ⚠ You must request access to a model before you can use it. If you try to use the model (with the API or console) before you have requested access to it, you will receive an error message. For more information, see [Model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html).
+<!--custom.prerequisites.end-->
+### Amazon Titan Text
+
+- [InvokeModel](src/main/kotlin/com/example/bedrockruntime/InvokeModel.kt#L6)
+
+
+<!--custom.examples.start-->
+<!--custom.examples.end-->
+
+## Run the examples
+
+### Instructions
+
+
+<!--custom.instructions.start-->
+<!--custom.instructions.end-->
+
+
+
+### Tests
+
+⚠ Running tests might result in charges to your AWS account.
+
+
+To find instructions for running these tests, see the [README](../../README.md#Tests)
+in the `kotlin` folder.
+
+
+
+<!--custom.tests.start-->
+<!--custom.tests.end-->
+
+## Additional resources
+
+- [Amazon Bedrock Runtime User Guide](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)
+- [Amazon Bedrock Runtime API Reference](https://docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html)
+- [SDK for Kotlin Amazon Bedrock Runtime reference](https://sdk.amazonaws.com/kotlin/api/latest/bedrock-runtime/index.html)
+
+<!--custom.resources.start-->
+<!--custom.resources.end-->
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0

kotlin/services/bedrock-runtime/build.gradle.kts

@@ -0,0 +1,54 @@
+plugins {
+    kotlin("jvm") version "2.1.10"
+    id("org.jetbrains.kotlin.plugin.serialization") version "2.1.10"
+    id("org.jlleitschuh.gradle.ktlint") version "11.3.1" apply true
+    application
+}
+
+group = "com.example.bedrockruntime"
+version = "1.0-SNAPSHOT"
+
+repositories {
+    mavenCentral()
+}
+
+buildscript {
+    repositories {
+        maven("https://plugins.gradle.org/m2/")
+    }
+    dependencies {
+        classpath("org.jlleitschuh.gradle:ktlint-gradle:11.3.1")
+    }
+}
+
+dependencies {
+    implementation("aws.sdk.kotlin:bedrockruntime:1.4.11")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json-jvm:1.8.0")
+    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
+}
+
+application {
+    mainClass.set("com.example.bedrockruntime.InvokeModelKt")
+}
+
+// Java and Kotlin configuration
+kotlin {
+    jvmToolchain(21)
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+tasks.test {
+    useJUnitPlatform()
+    testLogging {
+        events("passed", "skipped", "failed")
+    }
+
+    // Define the test source set
+    testClassesDirs += files("build/classes/kotlin/test")
+    classpath += files("build/classes/kotlin/main", "build/resources/main")
+}

kotlin/services/bedrock-runtime/src/main/kotlin/com/example/bedrockruntime/InvokeModel.kt

@@ -0,0 +1,67 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package com.example.bedrockruntime
+
+// snippet-start:[bedrock-runtime.kotlin.InvokeModel_AmazonTitanText]
+import aws.sdk.kotlin.services.bedrockruntime.BedrockRuntimeClient
+import aws.sdk.kotlin.services.bedrockruntime.model.InvokeModelRequest
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+
+/**
+ * Before running this Kotlin code example, set up your development environment, including your credentials.
+ *
+ * This example demonstrates how to invoke the Titan Text model (amazon.titan-text-lite-v1).
+ * Remember that you must enable the model before you can use it. See notes in the README.md file.
+ *
+ * For more information, see the following documentation topic:
+ * https://docs.aws.amazon.com/sdk-for-kotlin/latest/developer-guide/setup.html
+ */
+suspend fun main() {
+    val prompt = """
+        Write a short, funny story about a time-traveling cat who
+        ends up in ancient Egypt at the time of the pyramids.
+    """.trimIndent()
+
+    val response = invokeModel(prompt, "amazon.titan-text-lite-v1")
+    println("Generated story:\n$response")
+}
+
+suspend fun invokeModel(prompt: String, modelId: String): String {
+    BedrockRuntimeClient { region = "eu-central-1" }.use { client ->
+        val request = InvokeModelRequest {
+            this.modelId = modelId
+            contentType = "application/json"
+            accept = "application/json"
+            body = """
+                {
+                    "inputText": "${prompt.replace(Regex("\\s+"), " ").trim()}",
+                    "textGenerationConfig": {
+                        "maxTokenCount": 1000,
+                        "stopSequences": [],
+                        "temperature": 1,
+                        "topP": 0.7
+                    }
+                }
+            """.trimIndent().toByteArray()
+        }
+
+        val response = client.invokeModel(request)
+        val responseBody = response.body.toString(Charsets.UTF_8)
+
+        val jsonParser = Json { ignoreUnknownKeys = true }
+        return jsonParser
+            .decodeFromString<BedrockResponse>(responseBody)
+            .results
+            .first()
+            .outputText
+    }
+}
+
+@Serializable
+private data class BedrockResponse(val results: List<Result>)
+
+@Serializable
+private data class Result(val outputText: String)
+// snippet-end:[bedrock-runtime.kotlin.InvokeModel_AmazonTitanText]

kotlin/services/bedrock-runtime/src/test/kotlin/InvokeModelTest.kt

@@ -0,0 +1,24 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import com.example.bedrockruntime.invokeModel
+import kotlinx.coroutines.runBlocking
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.MethodOrderer.OrderAnnotation
+import org.junit.jupiter.api.Order
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.TestInstance
+import org.junit.jupiter.api.TestMethodOrder
+
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+@TestMethodOrder(OrderAnnotation::class)
+class InvokeModelTest {
+    @Test
+    @Order(1)
+    fun listFoundationModels() = runBlocking {
+        val prompt = "What is the capital of France?"
+
+        val answer = invokeModel(prompt, "amazon.titan-text-lite-v1")
+        assertTrue(answer.isNotBlank())
+    }
+}