Python: Added Hello bedrock runtime examples for Amazon Bedrock (#7244)

---------

Co-authored-by: Rachel Hagerman <[email protected]>

Author: AWSChris

.doc_gen/metadata/bedrock-runtime_metadata.yaml

@@ -21,6 +21,20 @@ bedrock-runtime_Hello:
             - description:
               snippet_files:
                 - javascriptv3/example_code/bedrock-runtime/hello.js
+
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/bedrock-runtime
+          sdkguide:
+          excerpts:
+            - description: Send a prompt to a model with the InvokeModel operation.
+              snippet_tags:
+                - bedrock-runtime.example_code.hello_bedrock_invoke.complete
+            - description: Send a user message to a model with the Converse operation.
+              snippet_tags:
+                - bedrock-runtime.example_code.hello_bedrock_converse.complete
+
   services:
     bedrock-runtime: {InvokeModel}
 

python/example_code/bedrock-runtime/README.md

@@ -38,6 +38,11 @@ python -m pip install -r requirements.txt
 > see [Model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html).
 >
 <!--custom.prerequisites.end-->
+
+### Get started
+
+- [Hello Amazon Bedrock Runtime](hello/hello_bedrock_runtime_invoke.py#L5) (`InvokeModel`)
+
 ### AI21 Labs Jurassic-2
 
 - [Converse](models/ai21_labs_jurassic2/converse.py#L4)
@@ -120,6 +125,13 @@ Mistral AI.
 
 <!--custom.instructions.end-->
 
+#### Hello Amazon Bedrock Runtime
+
+This example shows you how to get started using Amazon Bedrock Runtime.
+
+```
+python hello/hello_bedrock_runtime_invoke.py
+```
 
 
 ### Tests
@@ -148,4 +160,4 @@ in the `python` folder.
 
 Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 
-SPDX-License-Identifier: Apache-2.0
+SPDX-License-Identifier: Apache-2.0

python/example_code/bedrock-runtime/hello/hello_bedrock_runtime_converse.py

@@ -0,0 +1,83 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+
+# snippet-start:[bedrock-runtime.example_code.hello_bedrock_converse.complete]
+
+"""
+Uses the Amazon Bedrock runtime client Converse operation to send a user message to a model.
+"""
+import logging
+import boto3
+
+from botocore.exceptions import ClientError
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def converse(brt, model_id, user_message):
+    """
+    Uses the Converse operation to send a user message to the supplied model.
+    param brt: A bedrock runtime boto3 client
+    param model_id: The model ID for the model that you want to use.
+    param user message: The user message that you want to send to the model.
+
+    :return: The text response from the model.
+    """
+
+    # Format the request payload using the model's native structure.
+    conversation = [
+    {
+        "role": "user",
+        "content": [{"text": user_message}],
+    }
+]
+
+    try:
+        # Send the message to the model, using a basic inference configuration.
+        response = brt.converse(
+            modelId=model_id,
+            messages=conversation,
+            inferenceConfig={"maxTokens": 512, "temperature": 0.5, "topP": 0.9},
+        )
+
+        # Extract and print the response text.
+        response_text = response["output"]["message"]["content"][0]["text"]
+        return response_text
+
+    except (ClientError, Exception) as e:
+        print(f"ERROR: Can't invoke '{model_id}'. Reason: {e}")
+        raise
+
+
+def main():
+    """Entry point for the example. Uses the AWS SDK for Python (Boto3)
+    to create an Amazon Bedrock runtime client. Then sends a user message to a model
+    in the region set in the callers profile and credentials.
+    """
+
+    # Create an Amazon Bedrock Runtime client.
+    brt = boto3.client("bedrock-runtime")
+
+    # Set the model ID, e.g., Amazon Titan Text G1 - Express.
+    model_id = "amazon.titan-text-express-v1"
+
+    # Define the message for the model.
+    message = "Describe the purpose of a 'hello world' program in one line."
+
+    # Send the message to the model.
+    response = converse(brt, model_id, message)
+
+    print(f"Response: {response}")
+
+    logger.info("Done.")
+
+
+if __name__ == "__main__":
+    main()
+
+ # snippet-end:[bedrock-runtime.example_code.hello_bedrock_converse.complete]
+ 
+

python/example_code/bedrock-runtime/hello/hello_bedrock_runtime_invoke.py

@@ -0,0 +1,87 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+
+# snippet-start:[bedrock-runtime.example_code.hello_bedrock_invoke.complete]
+
+"""
+Uses the Amazon Bedrock runtime client InvokeModel operation to send a prompt to a model.
+"""
+import logging
+import json
+import boto3
+
+
+from botocore.exceptions import ClientError
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def invoke_model(brt, model_id, prompt):
+    """
+    Invokes the specified model with the supplied prompt.
+    param brt: A bedrock runtime boto3 client
+    param model_id: The model ID for the model that you want to use.
+    param prompt: The prompt that you want to send to the model.
+
+    :return: The text response from the model.
+    """
+
+    # Format the request payload using the model's native structure.
+    native_request = {
+        "inputText": prompt,
+        "textGenerationConfig": {
+            "maxTokenCount": 512,
+            "temperature": 0.5,
+            "topP": 0.9
+        }
+    }
+
+    # Convert the native request to JSON.
+    request = json.dumps(native_request)
+
+    try:
+        # Invoke the model with the request.
+        response = brt.invoke_model(modelId=model_id, body=request)
+
+        # Decode the response body.
+        model_response = json.loads(response["body"].read())
+
+        # Extract and print the response text.
+        response_text = model_response["results"][0]["outputText"]
+        return response_text
+
+    except (ClientError, Exception) as e:
+        print(f"ERROR: Can't invoke '{model_id}'. Reason: {e}")
+        raise
+
+
+def main():
+    """Entry point for the example. Uses the AWS SDK for Python (Boto3)
+    to create an Amazon Bedrock runtime client. Then sends a prompt to a model
+    in the region set in the callers profile and credentials.
+    """
+
+    # Create an Amazon Bedrock Runtime client.
+    brt = boto3.client("bedrock-runtime")
+
+    # Set the model ID, e.g., Amazon Titan Text G1 - Express.
+    model_id = "amazon.titan-text-express-v1"
+
+    # Define the prompt for the model.
+    prompt = "Describe the purpose of a 'hello world' program in one line."
+
+    # Send the prompt to the model.
+    response = invoke_model(brt, model_id, prompt)
+
+    print(f"Response: {response}")
+
+    logger.info("Done.")
+
+
+if __name__ == "__main__":
+    main()
+
+ # snippet-end:[bedrock-runtime.example_code.hello_bedrock_invoke.complete]

python/example_code/bedrock-runtime/test/test_hello_bedrock_runtime.py

@@ -0,0 +1,23 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import pytest
+import subprocess
+import sys
+
+files_under_test = [
+    # Text models
+    "hello/hello_bedrock_runtime_invoke.py"
+]
+
+
+@pytest.mark.integ
+@pytest.mark.parametrize("file", files_under_test)
+def test_hello_bedrock(file):
+    result = subprocess.run(
+        [sys.executable, file],
+        capture_output=True,
+        text=True,
+    )
+    assert result.stdout != ""
+    assert result.returncode == 0

python/example_code/bedrock-runtime/test/test_hello_bedrock_runtime_invoke.py

@@ -0,0 +1,24 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import pytest
+import subprocess
+import sys
+
+files_under_test = [
+    # Text models
+    "hello/hello_bedrock_runtime_invoke.py",
+    "hello/hello_bedrock_runtime_converse.py"
+]
+
+
+@pytest.mark.integ
+@pytest.mark.parametrize("file", files_under_test)
+def test_hello_bedrock(file):
+    result = subprocess.run(
+        [sys.executable, file],
+        capture_output=True,
+        text=True,
+    )
+    assert result.stdout != ""
+    assert result.returncode == 0