Merge remote-tracking branch 'origin/main' into 1458-persistent-chat

.github/labeler.yml

@@ -1,80 +1,78 @@
+# Copyright 2025 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+
 # Add 'root' label to any root file changes
 # Quotation marks are required for the leading asterisk
 root:
   - changed-files:
-      - any-glob-to-any-file: '*'
+      - any-glob-to-any-file: "*"
 
 docs:
   - changed-files:
       - any-glob-to-any-file:
-          - '**/*.md'
-          - '**/*.rst'
-          - 'LICENSE'
-          - 'docs-go/**'
-          - 'docs/**'
-          - 'py/engdocs/**'
+          - "**/*.md"
+          - "**/*.rst"
+          - "LICENSE"
+          - "docs-go/**"
+          - "docs/**"
+          - "py/engdocs/**"
 
 go:
   - changed-files:
       - any-glob-to-any-file:
-          - '**/*.go'
-          - '**/go.mod'
-          - '**/go.sum'
-          - 'go/**'
+          - "**/*.go"
+          - "**/go.mod"
+          - "**/go.sum"
+          - "go/**"
 
 python:
   - changed-files:
       - any-glob-to-any-file:
-          - '**/*.py'
-          - '**/pyproject.toml'
-          - 'py/**'
+          - "**/*.py"
+          - "**/pyproject.toml"
+          - "py/**"
 
 js:
   - changed-files:
       - any-glob-to-any-file:
-          - '**/*.js'
-          - '**/*.jsx'
-          - '**/*.ts'
-          - '**/*.tsx'
-          - '**/package.json'
-          - 'js/**'
+          - "**/*.js"
+          - "**/*.jsx"
+          - "**/*.ts"
+          - "**/*.tsx"
+          - "**/package.json"
+          - "js/**"
 
 tooling:
   - changed-files:
       - any-glob-to-any-file:
-          - 'genkit-tools/**'
+          - "genkit-tools/**"
 
 config:
   - changed-files:
       - any-glob-to-any-file:
-          - '**/*.toml'
-          - '**/*.yaml'
-          - '**/*.yml'
-          - '**/.editorconfig'
-          - '**/.github/**'
-          - '**/.gitignore'
-          - '**/.npmignore'
-          - '**/.npmrc'
-          - '**/.prettierignore'
-          - '**/package.json'
-          - '**/tsconfig.*.json'
-          - '**/tsconfig.json'
-          - '**/typedoc.json'
+          - "**/*.toml"
+          - "**/*.yaml"
+          - "**/*.yml"
+          - "**/.editorconfig"
+          - "**/.github/**"
+          - "**/.gitignore"
+          - "**/.npmignore"
+          - "**/.npmrc"
+          - "**/.prettierignore"
+          - "**/package.json"
+          - "**/tsconfig.*.json"
+          - "**/tsconfig.json"
+          - "**/typedoc.json"
 
 sample:
   - changed-files:
       - any-glob-to-any-file:
-          - 'samples/**'
+          - "samples/**"
 
 dotprompt:
   - changed-files:
       - any-glob-to-any-file:
-          - '**/dotprompt/**'
-
-handlebarz:
-  - changed-files:
-      - any-glob-to-any-file:
-          - '**/handlebarz/**'
+          - "**/dotprompt/**"
 
 # Automatically add labels to any PR also based on branch naming conventions.
 build:

.github/workflows/labeler.yml

@@ -1,3 +1,6 @@
+# Copyright 2025 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+
 name: "Pull Request Labeler"
 
 on:

.github/workflows/python.yml

@@ -1,3 +1,6 @@
+# Copyright 2025 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+
 name: Python Checks
 
 on: pull_request
@@ -11,9 +14,6 @@ jobs:
       matrix:
         python-version:
           - "3.12"
-    defaults:
-      run:
-        working-directory: py
 
     steps:
       - uses: actions/checkout@v4
@@ -28,16 +28,19 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Format check
-        run: uv run ruff format --check .
+        run: uv run --directory py ruff format --check .
 
       - name: Lint with ruff
-        run: uv run ruff check .
+        run: uv run --directory py ruff check --select I .
+
+      - name: Check licenses
+        run: ./bin/check_license
 
       - name: Run tests
-        run: ./bin/run_tests
+        run: ./py/bin/run_python_tests
 
       - name: Build documentation
-        run: uv run mkdocs build --strict
+        run: uv run --directory py mkdocs build --strict
 
       - name: Build distributions
-        run: ./bin/build_dists
+        run: ./py/bin/build_dists

.hooks/conventional-commit-msg

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+#
+# Copyright 2025 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+cat "$1" | convco check --from-stdin

.prettierignore

@@ -8,3 +8,4 @@ go/
 pnpm-lock.yaml
 public/
 py/*
+README.md

COMMIT_MESSAGE_TEMPLATE

@@ -0,0 +1,45 @@
+feat:
+
+ISSUE:
+
+CHANGELOG:
+  - []
+
+## COMMIT MESSAGE FULL EXAMPLE
+#
+# feat(py/plugins/vertexai): Implement two-factor authentication
+#
+# This commit introduces two-factor authentication for enhanced security.
+# It uses TOTP and requires users to configure an authenticator app.
+#
+# ISSUE: #123
+#
+# CHANGELOG:
+# - [ ] Add support for two-factor authentication
+# - [ ] Update user login endpoint to require two-factor authentication
+#
+# BREAKING CHANGE: The API endpoint for user login has been modified.
+
+## CONVENTIONAL COMMIT TEMPLATE
+#
+# Subject line (required, max 50 characters, use imperative mood):
+# <type>(<scope>): <short description>
+# Example: feat(user-authentication): Implement two-factor authentication
+#
+# Body (optional, wrap at 72 characters, explain the change in more detail, mention why and what):
+# <detailed description>
+
+## TYPES OF CHANGE (choose one):
+# - feat:       A new feature
+# - fix:        A bug fix
+# - docs:       Documentation changes
+# - style:      Code style changes (formatting, etc.)
+# - refactor:   Code refactoring (no new features or bug fixes)
+# - perf:       Performance improvements
+# - test:       Adding or modifying tests
+# - build:      Changes that affect the build system or external dependencies
+# - ci:         Changes to CI configuration files and scripts
+# - chore:      Routine tasks, build process changes, etc.
+# - revert:     Revert a previous commit
+#
+## SCOPE (optional, specify the affected area, e.g., component, module):

CONTRIBUTING.md

@@ -34,16 +34,56 @@ information on using pull requests.
 
 ## Setup
 
-### Environment
+Genkit supports JavaScript, Go, and Python. Before contributing in any of these languages, complete these prerequisites:
 
-1. [Install node v20](https://nodejs.org/en/download)
-2. Run `corepack enable pnpm` to enable pnpm.
+1. Install Node.js 20 or later using [nvm](https://nodejs.org/en/download)
 
-Note: We recommend using Node v20 or greater when compiling and running Genkit.
-Any older versions of Node may not work properly.
+   > **Note:** Node.js v20 or greater is required. Earlier versions may not work properly.
+
+2. Install the Genkit CLI globally:
+   ```bash
+   npm install -g genkit-cli
+   ```
+
+After completing these prerequisites, follow the language-specific setup instructions below.
+
+## Go Guide
+
+1. Install Go 1.24 or later
+   Follow the [official Go installation guide](https://golang.org/doc/install).
+
+2. Configure your AI model
+   Most samples use Google's Gemini model. You'll need to generate an API key at [Google AI Studio](https://aistudio.google.com/app/apikey).
+
+   Once you have your key, set it in your environment:
+
+   ```bash
+   export GOOGLE_GENAI_API_KEY=<your-api-key>
+   ```
+
+3. Run a sample application
+
+   ```bash
+   cd go/samples          # Navigate to samples directory
+   cd <sample-name>       # Choose a sample to run
+   go mod tidy            # Install Go dependencies
+   genkit start -- go run .  # Start the Genkit server and run the application
+   ```
+
+   Once running, visit http://localhost:4000 to access the Developer UI.
+
+4. Run tests
+   ```bash
+   cd <test-directory>    # Navigate to test directory
+   go test .              # Run tests in current directory
+   ```
+
+## JS Guide
 
 ### Install dependencies
 
+Run `corepack enable pnpm` to enable pnpm.
+
 ```
 pnpm i
 pnpm run setup
@@ -160,7 +200,7 @@ cd js && pnpm build && pnpm typedoc-html && open api-refs-js/index.html
 
 ## Send it
 
-Once done coding you will want to send a PR. Always do things in a separate branch (by convention name the branch `your_name-feature-something`).
+Once done coding you will want to send a PR. Always do things in a separate branch (by convention name the branch `your-name/feature-something`).
 
 Before sending the PR, always run:
 

bin/add_license

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+#
+# Copyright 2025 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+#
+# Adds a license header to all files that don't already have it.
+
+# set -x # Uncomment to enable tracing.
+set -euo pipefail
+
+TOP_DIR=$(git rev-parse --show-toplevel)
+
+if ! command -v addlicense &>/dev/null; then
+  if ! command -v go &>/dev/null; then
+    echo "Please install go"
+    exit 1
+  fi
+  echo "Installing addlicense..."
+  go install github.com/google/addlicense@latest
+fi
+
+# NOTE: If you edit the ignore patterns, make sure to update the ignore patterns
+# in the corresponding check_license script.
+$HOME/go/bin/addlicense \
+  -c "Google LLC" \
+  -s=only \
+  -l apache \
+  -ignore '**/.dist/**/*' \
+  -ignore '**/.eggs/**/*' \
+  -ignore '**/.idea/**/*' \
+  -ignore '**/.mypy_cache/**/*' \
+  -ignore '**/.next/**/*' \
+  -ignore '**/.output/**/*' \
+  -ignore '**/.pytest_cache/**/*' \
+  -ignore '**/.ruff_cache/**/*' \
+  -ignore '**/.venv/**/*' \
+  -ignore '**/.wxt/**/*' \
+  -ignore '**/__pycache__/**/*' \
+  -ignore '**/bazel-*/**/*' \
+  -ignore '**/coverage/**/*' \
+  -ignore '**/develop-eggs/**/*' \
+  -ignore '**/dist/**/*' \
+  -ignore '**/node_modules/**/*' \
+  -ignore '**/pnpm-lock.yaml' \
+  -ignore '.nx/**/*' \
+  -ignore '.trunk/**/*' \
+  "$TOP_DIR"

bin/check_license

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+#
+# Copyright 2025 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+#
+# Checks that all files have a license header.
+
+# set -x # Uncomment to enable tracing.
+set -euo pipefail
+
+TOP_DIR=$(git rev-parse --show-toplevel)
+
+if ! command -v addlicense &>/dev/null; then
+  if ! command -v go &>/dev/null; then
+    echo "Please install go"
+    exit 1
+  fi
+  echo "Installing addlicense..."
+  go install github.com/google/addlicense@latest
+fi
+
+export PATH=$(go env GOPATH):$PATH
+
+# NOTE: If you edit the ignore patterns, make sure to update the ignore patterns
+# in the corresponding add_license script.
+$HOME/go/bin/addlicense \
+  -check \
+  -c "Google LLC" \
+  -s=only \
+  -l apache \
+  -ignore '**/.dist/**/*' \
+  -ignore '**/.eggs/**/*' \
+  -ignore '**/.idea/**/*' \
+  -ignore '**/.mypy_cache/**/*' \
+  -ignore '**/.next/**/*' \
+  -ignore '**/.output/**/*' \
+  -ignore '**/.pytest_cache/**/*' \
+  -ignore '**/.ruff_cache/**/*' \
+  -ignore '**/.venv/**/*' \
+  -ignore '**/.wxt/**/*' \
+  -ignore '**/__pycache__/**/*' \
+  -ignore '**/bazel-*/**/*' \
+  -ignore '**/coverage/**/*' \
+  -ignore '**/develop-eggs/**/*' \
+  -ignore '**/dist/**/*' \
+  -ignore '**/node_modules/**/*' \
+  -ignore '**/pnpm-lock.yaml' \
+  -ignore '.nx/**/*' \
+  -ignore '.trunk/**/*' \
+  "$TOP_DIR"