refactor(py/samples): use a central script to run samples

py/bin/run_sample

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Runs a Python sample by name.
+# Usage: py/bin/run_sample <sample-name> [args...]
+# Example: py/bin/run_sample google-genai-hello
+#          py/bin/run_sample evaluator-demo
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PY_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SAMPLES_DIR="$PY_DIR/samples"
+
+# List available samples using find for robustness
+list_samples() {
+    # Only list directories that contain a run.sh script
+    find "$SAMPLES_DIR" -mindepth 1 -maxdepth 1 -type d -not -name '.*' -not -name '__pycache__' | while read -r dir; do
+        if [[ -f "$dir/run.sh" ]]; then
+            basename "$dir"
+        fi
+    done | sort
+}
+
+# Check if gum is available or install it
+GUM_CMD=""
+if command -v gum &> /dev/null; then
+    GUM_CMD="gum"
+elif [[ -f "$HOME/go/bin/gum" ]]; then
+    GUM_CMD="$HOME/go/bin/gum"
+elif command -v go &> /dev/null; then
+    read -p "gum not found. Would you like to install it using 'go install github.com/charmbracelet/gum@latest'? (y/N): " -n 1 -r
+    echo
+    if [[ $REPLY =~ ^[Yy]$ ]]; then
+        echo "Installing gum..."
+        if go install github.com/charmbracelet/gum@latest; then
+            GUM_CMD="$HOME/go/bin/gum"
+        fi
+    fi
+fi
+
+if [[ $# -lt 1 ]]; then
+    SAMPLES=$(list_samples)
+
+    if [[ -n "$GUM_CMD" ]]; then
+        SAMPLE_NAME=$($GUM_CMD filter --placeholder "Select a sample to run..." <<< "$SAMPLES")
+        if [[ -z "$SAMPLE_NAME" ]]; then
+            exit 0
+        fi
+    else
+        echo "Usage: $0 <sample-name> [args...]"
+        echo ""
+        echo "Available samples:"
+        echo "$SAMPLES"
+        exit 1
+    fi
+else
+    SAMPLE_NAME="$1"
+    shift
+fi
+
+SAMPLE_DIR="$SAMPLES_DIR/$SAMPLE_NAME"
+
+if [[ ! -d "$SAMPLE_DIR" ]]; then
+    echo "Error: Sample '$SAMPLE_NAME' not found in $SAMPLES_DIR"
+    echo ""
+    echo "Available samples:"
+    list_samples
+    exit 1
+fi
+
+cd "$SAMPLE_DIR"
+
+if [[ -f "./run.sh" ]]; then
+    exec ./run.sh "$@"
+else
+    echo "Error: Sample '$SAMPLE_NAME' does not have a 'run.sh' script."
+    exit 1
+fi

py/packages/genkit/src/genkit/web/typing.py

@@ -34,6 +34,7 @@
 
 try:
     import litestar  # type: ignore[misc]
+    import litestar.types  # type: ignore[misc]
 
     HAVE_LITESTAR = True
 except ImportError:
@@ -54,18 +55,18 @@
 # NOTE: Please ask these frameworks to standardize on asgiref.
 if HAVE_LITESTAR and HAVE_STARLETTE:
     Application = atyping.ASGIApplication | litestar.Litestar | StarletteApp
-    HTTPScope = atyping.HTTPScope | litestar.HTTPScope | starlette.types.Scope
-    LifespanScope = atyping.LifespanScope | litestar.LifespanScope | starlette.types.Scope
-    Receive = atyping.ASGIReceiveCallable | litestar.Receive | starlette.types.Scope
-    Scope = atyping.Scope | litestar.Scope | starlette.types.Scope
-    Send = atyping.ASGISendCallable | litestar.Send | starlette.types.Send
+    HTTPScope = atyping.HTTPScope | litestar.types.HTTPScope | starlette.types.Scope
+    LifespanScope = atyping.LifespanScope | litestar.types.LifeSpanScope | starlette.types.Scope
+    Receive = atyping.ASGIReceiveCallable | litestar.types.Receive | starlette.types.Scope
+    Scope = atyping.Scope | litestar.types.Scope | starlette.types.Scope
+    Send = atyping.ASGISendCallable | litestar.types.Send | starlette.types.Send
 elif HAVE_LITESTAR:
     Application = atyping.ASGIApplication | litestar.Litestar
-    HTTPScope = atyping.HTTPScope | litestar.HTTPScope
-    LifespanScope = atyping.LifespanScope | litestar.LifespanScope
-    Receive = atyping.ASGIReceiveCallable | litestar.Receive
-    Scope = atyping.Scope | litestar.Scope
-    Send = atyping.ASGISendCallable | litestar.Send
+    HTTPScope = atyping.HTTPScope | litestar.types.HTTPScope
+    LifespanScope = atyping.LifespanScope | litestar.types.LifeSpanScope
+    Receive = atyping.ASGIReceiveCallable | litestar.types.Receive
+    Scope = atyping.Scope | litestar.types.Scope
+    Send = atyping.ASGISendCallable | litestar.types.Send
 elif HAVE_STARLETTE:
     Application = StarletteApp | atyping.ASGIApplication
     HTTPScope = atyping.HTTPScope | starlette.types.Scope

py/samples/anthropic-hello/README.md

@@ -15,5 +15,5 @@ export ANTHROPIC_API_KEY=your-api-key
 
 3. Run the sample:
 ```bash
-genkit start -- uv run src/anthropic_hello.py
+genkit start -- uv run src/main.py
 ```

py/samples/anthropic-hello/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/compat-oai-hello/README.md

@@ -12,5 +12,5 @@ source .venv/bin/activate
 TODO
 
 ```bash
-genkit start -- uv run src/compat_oai_hello.py
+genkit start -- uv run src/main.py
 ```

py/samples/compat-oai-hello/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/dev-local-vectorstore-hello/README.md

@@ -13,5 +13,5 @@ source .venv/bin/activate
 TODO
 
 ```bash
-genkit start -- uv run --directory py samples/hello/src/hello.py
+genkit start -- uv run src/main.py
 ```

py/samples/dev-local-vectorstore-hello/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/evaluator-demo/README.md

@@ -2,14 +2,14 @@
 
 This sample demonstrates the different evaluation features using Genkit Python SDK.
 
-Note: This sample focuses on evaluation features in Genkit, by utilizing the official Genkit Evaluators plugin. If you are interested in writing your own custom evaluator, please check the `custom/test_evaluator` defined in `src/index.py`.
+Note: This sample focuses on evaluation features in Genkit, by utilizing the official Genkit Evaluators plugin. If you are interested in writing your own custom evaluator, please check the `custom/test_evaluator` defined in `src/main.py`.
 
 ## Setup and start the sample
 
 ```bash
 
 # Start the Genkit Dev UI
-genkit start -- uv run samples/evaluator-demo/src/index.py
+genkit start -- uv run src/main.py
 # This command should output the link to the Genkit Dev UI.
 ```
 

py/samples/evaluator-demo/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/firestore-retreiver/README.md

@@ -20,5 +20,5 @@ gcloud firestore indexes composite create \
 TODO
 
 ```bash
-genkit start -- uv run --directory py samples/firestore-retreiver/src/main.py
+genkit start -- uv run src/main.py
 ```

py/samples/firestore-retreiver/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/flask-hello/README.md

@@ -9,7 +9,7 @@ Use `gcloud auth application-default login` to connect to the VertexAI.
 TODO
 
 ```bash
-genkit start -- uv run flask --app src/flask_hello.py run
+genkit start -- uv run flask --app src/main.py run
 ```
 
 ```bash

py/samples/flask-hello/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run flask --app src/main.py run "$@"

py/samples/google-genai-code-execution/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/google-genai-context-caching/README.md

@@ -5,5 +5,5 @@
 TODO
 
 ```bash
-genkit start -- uv run google-genai-context-caching/src/context_caching.py
+genkit start -- uv run src/main.py
 ```

py/samples/google-genai-context-caching/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/google-genai-hello/README.md

@@ -16,7 +16,7 @@ export GEMINI_API_KEY='<Your api key>'
 ## Run the sample
 
 ```bash
-genkit start -- uv run src/google_genai_hello.py
+genkit start -- uv run src/main.py
 ```
 
 ### Testing GCP telemetry
@@ -40,5 +40,5 @@ To test Google Cloud Platform telemetry (tracing and metrics), you need a GCP pr
 
 3.  **Run with Telemetry**:
     ```bash
-    genkit start -- uv run src/google_genai_hello.py --enable-gcp-telemetry
+    genkit start -- uv run src/main.py --enable-gcp-telemetry
     ```

py/samples/google-genai-hello/pyproject.toml

@@ -53,7 +53,7 @@ build-backend = "hatchling.build"
 requires      = ["hatchling"]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/google_genai_hello"]
+packages = ["src/main.py"]
 
 [tool.hatch.metadata]
 allow-direct-references = true

py/samples/google-genai-hello/run.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Copyright 2025 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+exec genkit start -- uv run src/main.py "$@"

py/samples/google-genai-image/README.md

@@ -26,5 +26,5 @@ export GEMINI_API_KEY=<Your api key>
 TODO
 
 ```bash
-uv run src/google_genai_image.py
+uv run src/main.py
 ```