Add a README for /samples (#507)

* Add a README for /samples

* Add rest/README.md

* Add an action to keep updated

* Typo

* Fix action workflow

* Reworked action a bit

* Extra info line

.github/workflows/samples.yaml

@@ -0,0 +1,82 @@
+name: Validate samples
+
+on:
+  pull_request:
+    types: [opened, synchronize]  # new, updates
+
+jobs:
+  update-python-list:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Get Changed Files
+        id: changed_files
+        uses: tj-actions/changed-files@v44
+        with:
+          files:  |
+            samples/*.py
+
+      - name: Check Python samples
+        env:
+          NEW_FILES: ${{ steps.changed_files.outputs.all_modified_files }}
+          README: samples/README.md
+        run: |
+          #!/bin/bash
+          
+          for file in ${NEW_FILES}; do
+            echo "Testing $file"
+            if [[ -f ${file} ]]; then
+              # File exists, so needs to be listed.
+              if ! grep -q $name ${README}; then
+                echo "Error: Sample not listed in README ($name)"
+                exit 1
+              fi
+            else
+              # File does not exist, ensure it's not listed
+              if grep -q $name ${README}; then
+                echo "Error: Sample should not be listed in README ($name)"
+                exit 1
+              fi
+            fi
+          done
+
+  update-rest-list:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Get Changed Files
+        id: changed_files
+        uses: tj-actions/changed-files@v44
+        with:
+          files:  |
+            samples/rest/*.sh
+
+      - name: Check REST samples
+        env:
+          NEW_FILES: ${{ steps.changed_files.outputs.all_modified_files }}
+          README: samples/rest/README.md
+        run: |
+          #!/bin/bash
+          
+          for file in ${NEW_FILES}; do
+            echo "Testing $file"
+            if [[ -f ${file} ]]; then
+              # File exists, so needs to be listed.
+              if ! grep -q $name ${README}; then
+                echo "Error: Sample not listed in README ($name)"
+                exit 1
+              fi
+            else
+              # File does not exist, ensure it's not listed
+              if grep -q $name ${README}; then
+                echo "Error: Sample should not be listed in README ($name)"
+                exit 1
+              fi
+            fi
+          done

samples/README.md

@@ -0,0 +1,26 @@
+# Gemini API Python SDK sample code
+
+This directory contains sample code for key features of the SDK, organised by high level feature.
+
+These samples are embedded in parts of the [documentation](https://ai.google.dev), most notably in the [API reference](https://ai.google.dev/api).
+
+Each file is structured as a runnable test case, ensuring that samples are executable and functional. Each test demonstrates a single concept, and contains region tags that are used to demarcate the test scaffolding from the spotlight code. If you are contributing, code within region tags should follow sample code best practices - being clear, complete and concise.
+
+## Contents
+
+| File | Description |
+| ---- | ----------- |
+| [cache.py](./cache.py) | Context caching |
+| [chat.py](./chat.py) | Multi-turn chat conversations |
+| [code_execution.py](./code_execution.py) | Executing code |
+| [configure_model_parameters.py](./configure_model_parameters.py) | Setting model parameters |
+| [controlled_generation.py](./controlled_generation.py) | Generating content with output constraints (e.g. JSON mode) |
+| [count_tokens.py](./count_tokens.py) | Counting input and output tokens |
+| [embed.py](./embed.py) | Generating embeddings |
+| [files.py](./files.py) | Managing files with the File API |
+| [function_calling.py](./function_calling.py) | Using function calling |
+| [models.py](./models.py) | Listing models and model metadata |
+| [safety_settings.py](./safety_settings.py) | Setting and using safety controls |
+| [system_instruction.py](./system_instruction.py) | Setting system instructions |
+| [text_generation.py](./text_generation.py) | Generating text |
+| [tuned_models.py](./tuned_models.py) | Creating and managing tuned models |

samples/rest/README.md

@@ -0,0 +1,25 @@
+# Gemini API REST sample code
+
+This directory contains sample code for key features of the API, organised by high level feature.
+
+These samples are embedded in parts of the [documentation](https://ai.google.dev), most notably in the [API reference](https://ai.google.dev/api).
+
+Each file is structured as a runnable script, ensuring that samples are executable and functional. Each filee contains region tags that are used to demarcate the script from the spotlight code. If you are contributing, code within region tags should follow sample code best practices - being clear, complete and concise.
+
+## Contents
+
+| File | Description |
+| ---- | ----------- |
+| [cache.sh](./cache.sh) | Context caching |
+| [chat.sh](./chat.sh) | Multi-turn chat conversations |
+| [code_execution.sh](./code_execution.sh) | Executing code |
+| [configure_model_parameters.sh](./configure_model_parameters.sh) | Setting model parameters |
+| [controlled_generation.sh](./controlled_generation.sh) | Generating content with output constraints (e.g. JSON mode) |
+| [count_tokens.sh](./count_tokens.sh) | Counting input and output tokens |
+| [embed.sh](./embed.sh) | Generating embeddings |
+| [files.sh](./files.sh) | Managing files with the File API |
+| [function_calling.sh](./function_calling.sh) | Using function calling |
+| [models.sh](./models.sh) | Listing models and model metadata |
+| [safety_settings.sh](./safety_settings.sh) | Setting and using safety controls |
+| [system_instruction.sh](./system_instruction.sh) | Setting system instructions |
+| [text_generation.sh](./text_generation.sh) | Generating text |