AWS code-library documentation change
Summary
Added documentation for Amazon Nova model usage with Bedrock's Converse and ConverseStream APIs, updated Titan Text example to use structured error handling and simplified parameters
Security assessment
Changes focus on adding new model integration examples and improving code quality/structure. No security vulnerabilities, mitigations, or security feature documentation are mentioned. Updates include error handling improvements and parameter adjustments without security context.
Diff
diff --git a/code-library/latest/ug/kotlin_1_bedrock-runtime_code_examples.md b/code-library/latest/ug/kotlin_1_bedrock-runtime_code_examples.md index ab839b544..2c6fa4767 100644 --- a/code-library/latest/ug/kotlin_1_bedrock-runtime_code_examples.md +++ b/code-library/latest/ug/kotlin_1_bedrock-runtime_code_examples.md @@ -5 +5 @@ -Amazon Titan Text +Amazon NovaAmazon Titan Text @@ -16,0 +17 @@ Each example includes a link to the complete source code, where you can find ins + * Amazon Nova @@ -20,0 +22,171 @@ Each example includes a link to the complete source code, where you can find ins +## Amazon Nova + +The following code example shows how to send a text message to Amazon Nova, using Bedrock's Converse API. + +**SDK for Kotlin** + + +###### Note + +There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/bedrock-runtime#code-examples). + +Send a text message to Amazon Nova, using Bedrock's Converse API. + + + import aws.sdk.kotlin.services.bedrockruntime.BedrockRuntimeClient + import aws.sdk.kotlin.services.bedrockruntime.model.ContentBlock + import aws.sdk.kotlin.services.bedrockruntime.model.ConversationRole + import aws.sdk.kotlin.services.bedrockruntime.model.ConverseRequest + import aws.sdk.kotlin.services.bedrockruntime.model.Message + + /** + * This example demonstrates how to use the Amazon Nova foundation models to generate text. + * It shows how to: + * - Set up the Amazon Bedrock runtime client + * - Create a message + * - Configure and send a request + * - Process the response + */ + suspend fun main() { + converse().also { println(it) } + } + + suspend fun converse(): String { + // Create and configure the Bedrock runtime client + BedrockRuntimeClient { region = "us-east-1" }.use { client -> + + // Specify the model ID. For the latest available models, see: + // https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html + val modelId = "amazon.nova-lite-v1:0" + + // Create the message with the user's prompt + val prompt = "Describe the purpose of a 'hello world' program in one line." + val message = Message { + role = ConversationRole.User + content = listOf(ContentBlock.Text(prompt)) + } + + // Configure the request with optional model parameters + val request = ConverseRequest { + this.modelId = modelId + messages = listOf(message) + inferenceConfig { + maxTokens = 500 // Maximum response length + temperature = 0.5F // Lower values: more focused output + // topP = 0.8F // Alternative to temperature + } + } + + // Send the request and process the model's response + runCatching { + val response = client.converse(request) + return response.output!!.asMessage().content.first().asText() + }.getOrElse { error -> + error.message?.let { e -> System.err.println("ERROR: Can't invoke '$modelId'. Reason: $e") } + throw RuntimeException("Failed to generate text with model $modelId", error) + } + } + } + + + + * For API details, see [Converse](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in _AWS SDK for Kotlin API reference_. + + + + +The following code example shows how to send a text message to Amazon Nova, using Bedrock's Converse API and process the response stream in real-time. + +**SDK for Kotlin** + + +###### Note + +There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/bedrock-runtime#code-examples). + +Send a text message to Amazon Nova using Bedrock's Converse API and process the response stream in real-time. + + + import aws.sdk.kotlin.services.bedrockruntime.BedrockRuntimeClient + import aws.sdk.kotlin.services.bedrockruntime.model.ContentBlock + import aws.sdk.kotlin.services.bedrockruntime.model.ConversationRole + import aws.sdk.kotlin.services.bedrockruntime.model.ConverseStreamOutput + import aws.sdk.kotlin.services.bedrockruntime.model.ConverseStreamRequest + import aws.sdk.kotlin.services.bedrockruntime.model.Message + + /** + * This example demonstrates how to use the Amazon Nova foundation models + * to generate streaming text responses. + * It shows how to: + * - Set up the Amazon Bedrock runtime client + * - Create a message with a prompt + * - Configure a streaming request with parameters + * - Process the response stream in real time + */ + suspend fun main() { + converseStream() + } + + suspend fun converseStream(): String { + // A buffer to collect the complete response + val completeResponseBuffer = StringBuilder() + + // Create and configure the Bedrock runtime client + BedrockRuntimeClient { region = "us-east-1" }.use { client -> + + // Specify the model ID. For the latest available models, see: + // https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html + val modelId = "amazon.nova-lite-v1:0" + + // Create the message with the user's prompt + val prompt = "Describe the purpose of a 'hello world' program in a paragraph." + val message = Message { + role = ConversationRole.User + content = listOf(ContentBlock.Text(prompt)) + } + + // Configure the request with optional model parameters + val request = ConverseStreamRequest { + this.modelId = modelId + messages = listOf(message) + inferenceConfig { + maxTokens = 500 // Maximum response length + temperature = 0.5F // Lower values: more focused output + // topP = 0.8F // Alternative to temperature + } + } + + // Process the streaming response + runCatching { + client.converseStream(request) { response -> + response.stream?.collect { chunk -> + when (chunk) { + is ConverseStreamOutput.ContentBlockDelta -> { + // Process each text chunk as it arrives + chunk.value.delta?.asText()?.let { text -> + print(text) + System.out.flush() // Ensure immediate output + completeResponseBuffer.append(text) + } + } + else -> {} // Other output block types can be handled as needed + } + } + } + }.onFailure { error -> + error.message?.let { e -> System.err.println("ERROR: Can't invoke '$modelId'. Reason: $e") } + throw RuntimeException("Failed to generate text with model $modelId: $error", error) + } + } + + return completeResponseBuffer.toString() + } + + + + + * For API details, see [ConverseStream](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in _AWS SDK for Kotlin API reference_. + + + + @@ -41,7 +213,6 @@ Use the Invoke Model API to generate a short story. - * 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 + * This example demonstrates how to use the Amazon Titan foundation models to generate text. + * It shows how to: + * - Set up the Amazon Bedrock runtime client + * - Create a request payload + * - Configure and send a request + * - Process the response @@ -50,4 +221,2 @@ Use the Invoke Model API to generate a short story. - 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()