refactor(genai): refactor GenAI code samples (#13166)

* refactor(genai): Update docs, filename and comments

* update template folder examples

* refactor(genai): Update docs, filename and comments

* update template folder examples

* refactor(genai): Update docs, filename and comments

* update template folder examples

* refactor(genai): clean unused file & update pkg version

* refactor(genai): rollback accidental changes

* docs(genai): update readme pages

* docs(genai): Temporarily restoring old region tags

* docs(genai): Temporarily restoring old region tags

Author: msampathkumar

genai/README.md

@@ -1,45 +1,65 @@
 # Generative AI Samples on Google Cloud
 
-Welcome to the Python samples folder for Generative AI on Vertex AI! In this folder, you can find the Python samples
-used in [Google Cloud Generative AI documentation](https://cloud.google.com/ai/generative-ai?hl=en).
-
-If you are looking for colab notebook, then please check https://github.com/GoogleCloudPlatform/generative-ai.
+This directory contains Python code samples demonstrating how to use Google Cloud's Generative AI capabilities on Vertex AI. These samples accompany the [Google Cloud Generative AI documentation](https://cloud.google.com/ai/generative-ai) and provide practical examples of various features and use cases.
 
 ## Getting Started
 
-To try and run these Code samples, we recommend using Google Cloud IDE or Google Colab.
+To run these samples, we recommend using either Google Cloud Shell, Cloud Code IDE, or Google Colab. You'll need a Google Cloud Project and appropriate credentials.
+
+**Prerequisites:**
+
+- **Google Cloud Project:** Create or select a project in the [Google Cloud Console](https://console.cloud.google.com).
+- **Authentication:** Ensure you've authenticated with your Google Cloud account. See the [authentication documentation](https://cloud.google.com/docs/authentication) for details.
+- **Enable the Vertex AI API:** Enable the API in your project through the [Cloud Console](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com).
+
+## Sample Categories
+
+The samples are organized into the following categories:
+
+### Batch Prediction (`batch_prediction`)
+
+Demonstrates how to use batch prediction with Generative AI models. This allows efficient processing of large datasets. See the [Batch Prediction documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/batch-prediction-gemini) for more details.
+
+### Content Cache (`content_cache`)
+
+Illustrates how to create, update, use, and delete content caches. Caches store frequently used content to improve performance and reduce costs. See the [Content Cache documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-overview) for more information.
+
+### Controlled Generation (`controlled_generation`)
+
+Provides examples of how to control various aspects of the generated content, such as length, format, safety attributes, and more. This allows for tailoring the output to specific requirements and constraints. See the [Controlled Generation documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/control-generated-output) for details.
+
+### Count Tokens (`count_tokens`)
+
+Shows how to estimate token usage for inputs and outputs of Generative AI models. Understanding token consumption is crucial for managing costs and optimizing performance. See the [Token Counting documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/list-token) for more details.
+
+### Express Mode (`express_mode`)
+
+Demonstrates how to use Express Mode for simpler and faster interactions with Generative AI models using an API key. This mode is ideal for quick prototyping and experimentation. See the [Express Mode documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) for details.
+
+### Live API (`live_api`)
+
+Provides examples of using the Generative AI [Live API](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal-live-api). This allows for real-time interactions and dynamic content generation.
+
+### Safety (`safety`)
 
-Note: A Google Cloud Project is a pre-requisite.
+Provides examples demonstrating how to configure and apply safety settings to Generative AI models. This includes techniques for content filtering and moderation to ensure responsible AI usage. See the [Safety documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/configure-safety-attributes) for details.
 
-## Features folders
+### Text Generation (`text_generation`)
 
-All GenAI code samples are organised into folders, referred as Feature folders.
+Provides examples of generating text using various input modalities (text, images, audio, video) and features like asynchronous generation, chat, and text streaming. See the [Text Generation documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/send-chat-prompts-gemini) for details.
 
-### Features
+### Tools (`tools`)
 
-<table>
-  <tr>
-   <td><strong>Python Samples Folder</strong>
-   </td>
-   <td><strong>Google Cloud Product</strong>
-   </td>
-   <td><strong>Short Description</strong></td>
-  </tr>
-  <tr>
-   <td>[Template Folder](/template_folder) </td>
-   <td><a href="add-link-here">Link to the feature</a> </td>
-   <td>Short description</td>
-  </tr>
-</table>
+Showcases how to use tools like function calling, code execution, and grounding with Google Search to enhance Generative AI interactions. See the [Tools documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/function-calling) for more information.
 
 ## Contributing
 
-Contributions welcome! See the [Contributing Guide](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/CONTRIBUTING.md).
+Contributions are welcome! See the [Contributing Guide](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/CONTRIBUTING.md).
 
-## Getting help
+## Getting Help
 
-Please use the [issues page](https://github.com/GoogleCloudPlatform/python-docs-samples/issues) to provide suggestions, feedback or submit a bug report.
+For questions, feedback, or bug reports, please use the [issues page](https://github.com/GoogleCloudPlatform/python-docs-samples/issues).
 
 ## Disclaimer
 
-This repository itself is not an officially supported Google product. The code in this repository is for demonstrative purposes only.
+This repository is not an officially supported Google product. The code is provided for demonstrative purposes only.

genai/batch_prediction/noxfile_config.py

@@ -0,0 +1,42 @@
+# Copyright 2021 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.
+
+# Default TEST_CONFIG_OVERRIDE for python repos.
+
+# You can copy this file into your directory, then it will be imported from
+# the noxfile.py.
+
+# The source of truth:
+# https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/noxfile_config.py
+
+TEST_CONFIG_OVERRIDE = {
+    # You can opt out from the test for specific Python versions.
+    "ignored_versions": ["2.7", "3.7", "3.8", "3.10", "3.11", "3.12"],
+    # Old samples are opted out of enforcing Python type hints
+    # All new samples should feature them
+    "enforce_type_hints": True,
+    # An envvar key for determining the project id to use. Change it
+    # to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
+    # build specific Cloud project. You can also use your own string
+    # to use your own Cloud project.
+    "gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
+    # 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
+    # If you need to use a specific version of pip,
+    # change pip_version_override to the string representation
+    # of the version number, for example, "20.2.4"
+    "pip_version_override": None,
+    # A dictionary you want to inject into your test. Don't put any
+    # secrets here. These values will override predefined values.
+    "envs": {},
+}

genai/batch_prediction/test_batch_predict.py renamed to genai/batch_prediction/test_batch_prediction_examples.py

@@ -12,7 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+#
+# Using Google Cloud Vertex AI to test the code samples.
+#
+
 from datetime import datetime as dt
+
 import os
 
 from google.cloud import bigquery, storage
@@ -33,7 +38,7 @@
 
 
 @pytest.fixture(scope="session")
-def bq_output_uri():
+def bq_output_uri() -> str:
     table_name = f"text_output_{dt.now().strftime('%Y_%m_%d_T%H_%M_%S')}"
     table_uri = f"{BQ_OUTPUT_DATASET}.{table_name}"
 
@@ -44,7 +49,7 @@ def bq_output_uri():
 
 
 @pytest.fixture(scope="session")
-def gcs_output_uri():
+def gcs_output_uri() -> str:
     prefix = f"text_output/{dt.now()}"
 
     yield f"gs://{GCS_OUTPUT_BUCKET}/{prefix}"
@@ -56,11 +61,11 @@ def gcs_output_uri():
         blob.delete()
 
 
-def test_batch_prediction_with_bq(bq_output_uri) -> None:
+def test_batch_prediction_with_bq(bq_output_uri: str) -> None:
     response = batchpredict_with_bq.generate_content(output_uri=bq_output_uri)
     assert response == JobState.JOB_STATE_SUCCEEDED
 
 
-def test_batch_prediction_with_gcs(gcs_output_uri) -> None:
+def test_batch_prediction_with_gcs(gcs_output_uri: str) -> None:
     response = batchpredict_with_gcs.generate_content(output_uri=gcs_output_uri)
     assert response == JobState.JOB_STATE_SUCCEEDED

genai/content_cache/contentcache_use_with_txt.py

@@ -23,8 +23,8 @@ def generate_content(cache_name: str) -> str:
     # Use content cache to generate text response
     # E.g cache_name = 'projects/111111111111/locations/us-central1/cachedContents/1111111111111111111'
     response = client.models.generate_content(
-        model='gemini-1.5-pro-002',
-        contents='Summarize the pdfs',
+        model="gemini-1.5-pro-002",
+        contents="Summarize the pdfs",
         config=GenerateContentConfig(
             cached_content=cache_name,
         ),

genai/controlled_generation/test_controlled_generation_samples.py renamed to genai/controlled_generation/test_controlled_generation_examples.py

@@ -13,8 +13,10 @@
 # limitations under the License.
 
 
-def compute_tokens() -> int:
+def compute_tokens_example() -> int:
+    # TODO: Remove `count_tokens` region tags after Feb 2025
     # [START googlegenaisdk_count_tokens_compute_with_txt]
+    # [START googlegenaisdk_counttoken_compute_with_txt]
     from google import genai
     from google.genai.types import HttpOptions
 
@@ -32,9 +34,10 @@ def compute_tokens() -> int:
     #    tokens=[b'What', b"'", b's', b' the', b' longest', b' word', b' in', b' the', b' English', b' language', b'?']
     #  )]
 
+    # [END googlegenaisdk_counttoken_compute_with_txt]
     # [END googlegenaisdk_count_tokens_compute_with_txt]
     return response.tokens_info
 
 
 if __name__ == "__main__":
-    compute_tokens()
+    compute_tokens_example()

genai/count_tokens/count_tokens_compute_with_txt.py renamed to genai/count_tokens/counttoken_compute_with_txt.py

@@ -13,8 +13,10 @@
 # limitations under the License.
 
 
-def generate_content() -> int:
+def count_tokens_example() -> int:
+    # TODO: Remove `count_tokens` region tags after Feb 2025
     # [START googlegenaisdk_count_tokens_resp_with_txt]
+    # [START googlegenaisdk_counttoken_resp_with_txt]
     from google import genai
     from google.genai.types import HttpOptions
 
@@ -36,9 +38,10 @@ def generate_content() -> int:
     #  prompt_token_count=6
     #  total_token_count=317
 
+    # [END googlegenaisdk_counttoken_resp_with_txt]
     # [END googlegenaisdk_count_tokens_resp_with_txt]
     return response.usage_metadata
 
 
 if __name__ == "__main__":
-    generate_content()
+    count_tokens_example()

genai/count_tokens/count_tokens_resp_with_txt.py renamed to genai/count_tokens/counttoken_resp_with_txt.py

@@ -14,7 +14,9 @@
 
 
 def count_tokens() -> int:
+    # TODO: Remove `count_tokens` region tags after Feb 2025
     # [START googlegenaisdk_count_tokens_with_txt]
+    # [START googlegenaisdk_counttoken_with_txt]
     from google import genai
     from google.genai.types import HttpOptions
 
@@ -28,6 +30,7 @@ def count_tokens() -> int:
     # total_tokens=10
     # cached_content_token_count=None
 
+    # [END googlegenaisdk_counttoken_with_txt]
     # [END googlegenaisdk_count_tokens_with_txt]
     return response.total_tokens
 

genai/count_tokens/count_tokens_with_txt.py renamed to genai/count_tokens/counttoken_with_txt.py

@@ -14,7 +14,9 @@
 
 
 def count_tokens() -> int:
+    # TODO: Remove `count_tokens` region tags after Feb 2025
     # [START googlegenaisdk_count_tokens_with_txt_img_vid]
+    # [START googlegenaisdk_counttoken_with_txt_vid]
     from google import genai
     from google.genai.types import HttpOptions, Part
 
@@ -37,6 +39,7 @@ def count_tokens() -> int:
     # Example output:
     # total_tokens=10 cached_content_token_count=None
 
+    # [END googlegenaisdk_counttoken_with_txt_vid]
     # [END googlegenaisdk_count_tokens_with_txt_img_vid]
     return response.total_tokens
 

genai/count_tokens/count_tokens_with_txt_img_vid.py renamed to genai/count_tokens/counttoken_with_txt_img_vid.py

@@ -18,28 +18,28 @@
 
 import os
 
-import count_tokens_compute_with_txt
-import count_tokens_resp_with_txt
-import count_tokens_with_txt
-import count_tokens_with_txt_img_vid
+import counttoken_compute_with_txt
+import counttoken_resp_with_txt
+import counttoken_with_txt
+import counttoken_with_txt_img_vid
 
 os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
 os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"
 # The project name is included in the CICD pipeline
 # os.environ['GOOGLE_CLOUD_PROJECT'] = "add-your-project-name"
 
 
-def test_count_tokens_compute_with_txt() -> None:
-    assert count_tokens_compute_with_txt.compute_tokens()
+def test_counttoken_compute_with_txt() -> None:
+    assert counttoken_compute_with_txt.compute_tokens_example()
 
 
-def test_count_tokens_resp_with_txt() -> None:
-    assert count_tokens_resp_with_txt.generate_content()
+def test_counttoken_resp_with_txt() -> None:
+    assert counttoken_resp_with_txt.count_tokens_example()
 
 
-def test_count_tokens_with_txt() -> None:
-    assert count_tokens_with_txt.count_tokens()
+def test_counttoken_with_txt() -> None:
+    assert counttoken_with_txt.count_tokens()
 
 
-def test_count_tokens_with_txt_img_vid() -> None:
-    assert count_tokens_with_txt_img_vid.count_tokens()
+def test_counttoken_with_txt_img_vid() -> None:
+    assert counttoken_with_txt_img_vid.count_tokens()