Merge branch 'main' into fix/issue-3575

Author: rohityan

.agents/skills/adk-review/SKILL.md

@@ -24,24 +24,30 @@ This skill guides AI assistants in performing a comprehensive, rigorous review o
   - **Boundary and Null Conditions**: Ensure robust handling for boundary conditions and null values (e.g., `None`, empty collections, zero, or empty strings) using validation or fallback defaults.
   - **Preconditions & Invariants**: Validate that preconditions and state invariants are checked before performing core logic.
 
-### 2. Style and Convention Compliance
+### 2. Code Quality & Design
+- **Complexity & Readability**: Identify overly complex functions or classes. Suggest refactoring (e.g., splitting functions, extracting helper classes) to improve readability and maintainability. Ensure code is self-documenting.
+- **Design Patterns**: Check if appropriate design patterns are used. Avoid anti-patterns. Ensure high cohesion and low coupling.
+- **Performance & Efficiency**: Look for performance bottlenecks, such as unnecessary database queries, redundant computations, inefficient loops, or excessive memory allocation.
+- **Security & Privacy**: Verify that inputs are validated, sensitive data is handled securely, and there are no potential security vulnerabilities (like injection, resource exhaustion, or exposure of internal state).
+
+### 3. Style and Convention Compliance
 - **ADK Style Guide**: Cross-reference all code changes with the guidelines in the `adk-style` skill (including Pydantic v2 patterns, lazy logging evaluation, and file structure).
 - **Pre-commit Hooks**: Ensure changed files are formatted and linted. Remind the user to run `pre-commit run --files <files>` if hooks like `isort`, `pyink`, `addlicense`, or `mdformat` are not configured automatically.
 
-### 3. Architectural Integrity & Unintended Outcomes
+### 4. Architectural Integrity & Unintended Outcomes
 - **Public API Stability**: Verify whether changes modify, remove, or restrict public-facing interfaces, classes, methods, argument lists, or CLI structures (e.g., in the public package namespaces under `src/google/adk/`). Breaking changes are unacceptable without a formal deprecation cycle under Semantic Versioning.
 - **Execution & Resumption**: If changing workflows, nodes, or state management, ensure compatibility with the ADK 2.0 event execution lifecycle and session resumption (HITL/checkpoints).
 - **Concurrency & Safety**: Check for race conditions or resource leaks. Ensure long-running or shared resources (like plugins, exporters, and connections) are closed/disposed of safely.
 
-### 4. Documentation Impact (`docs/design` and `docs/guides`)
+### 5. Documentation Impact (`docs/design` and `docs/guides`)
 - **Design & Architecture**: Determine if the change updates a core design contract. If so, check if design docs under `docs/design/` require updates or new documents need to be written.
 - **Guides**: If the changes introduce a new feature or change a public API/workflow pattern, check if the guides under `docs/guides/` need updates.
 
-### 5. Sample Compatibility & Updates
+### 6. Sample Compatibility & Updates
 - **Sample Integrity**: Verify if existing samples under `contributing/samples/` are affected by the change.
 - **New Samples**: If the changes introduce a key new capability, assess whether a new sample should be added to demonstrate the feature (following `adk-sample-creator` conventions).
 
-### 6. Test Coverage & Quality
+### 7. Test Coverage & Quality
 - **Coverage**: Ensure that all modified or new code paths have corresponding unit or integration tests under `tests/`.
 - **ADK Test Rules**: Ensure test implementations adhere to the 9 rules in the `adk-style` testing reference (e.g., using deterministic IDs, event normalization, and clean up utilities).
 
@@ -55,12 +61,13 @@ When the `adk-review` skill is triggered, you MUST execute the following steps:
 Run `git status` and `git diff` to identify exactly which files have been modified, added, or deleted.
 
 ### Step 2: Perform the Multi-Dimensional Review
-Analyze the retrieved diffs file-by-file against the six dimensions in the Checklist. Identify any errors, deviations, or missing files (such as docs, tests, or samples).
+Analyze the retrieved diffs file-by-file against the seven dimensions in the Checklist. Identify any errors, deviations, or missing files (such as docs, tests, or samples).
 
 ### Step 3: Generate and Present a Review Report
 Generate a clear, beautifully formatted Markdown report categorized by priority:
-- 🔴 **Critical Errors / Bugs**: Syntax, type safety violations, race conditions, or resource leaks.
-- 🟡 **Style & Conventions**: Lints, formatting issues, non-lazy logging, or typing mismatches.
+- 🔴 **Critical Errors, Bugs, & Security**: Syntax, type safety violations, race conditions, resource leaks, or security vulnerabilities.
+- 🟠 **Code Quality & Design**: High complexity, poor readability, performance bottlenecks, or architectural misalignment.
+- 🟡 **Style & Conventions**: Lints, formatting issues, non-lazy logging, or minor typing mismatches.
 - 🔵 **Documentation, Tests, & Samples**: Missing or stale test coverage, design docs, or user guides.
 
 Include the specific filename and line number/context for each finding.

.agents/skills/adk-sample-creator/SKILL.md

@@ -91,6 +91,7 @@ Each sample should have a `README.md` with the following structure:
 - **Sample Inputs**: Examples of inputs to test with. Each prompt must be wrapped in backticks. If a prompt has an explanation, always add a blank line between the prompt and the explanation, and indent the explanation by two spaces.
 - **Graph**: Visualization of the graph flow (Mermaid recommended for workflows).
 - **How To**: Explanation of key techniques used (e.g., `ctx.run_node`).
+- **Related Guides**: Links to relevant developer guides in `docs/guides/` that explain the concepts or classes used.
 
 #### README Example Template:
 
@@ -116,12 +117,13 @@ graph TD
     START --> MyNode
 ```
 
-````
-
 ## How To
 
 Explain the details.
 
+## Related Guides
+
+- [Guide Title](../../docs/guides/path/to/guide.md) - Brief description of what the guide covers.
 ````
 
 ## Examples

.agents/skills/adk-setup/SKILL.md

@@ -10,7 +10,7 @@ Set up the local development environment for ADK Python.
 
 Check the following before proceeding:
 
-1. **Python 3.11+**
+1. **Python 3.10+**
 
    ```bash
    python3 --version

.agents/skills/adk-unit-guide/SKILL.md

@@ -28,6 +28,7 @@ This skill creates a detailed developer guide for new or updated code file or di
 - Look for an existing guide in the `/docs/guides/***` directory of this repository.
   - If a guide already exists, update the existing guide incrementally and prioritize preserving the previous content as much as possible.
   - If no guide exists, create a guide file for the new code unit in the `/docs/guides/***` directory of this repository, using the relative path of the code unit. For example, if the code unit is called `/topic/function/class.ext`, create a guide in the location `/docs/guides/topic/function/class/index.md`.
+- **Update the Index**: Whenever a new guide is created, or an existing guide's title/summary changes, update the index file `/docs/guides/README.md`. Ensure the guide is listed under the correct category with a link and a brief summary.
 
 ### Guide structure and content
 
@@ -50,6 +51,8 @@ Use the following structure and instructions to create the guide for the code un
 - Present a single, minimum implementation of the code unit to demonstrate its use.
 - Show enough of the containing classes to make it clear where the code could be used.
 - Use unit test code as a starting point for the code example, if available.
+- When writing a sample agent, do not set the `model` attribute.
+- For workflow node samples, prefer using a simple Python function rather than extending `BaseNode` to demonstrate the node's logic, unless class extension is explicitly required for the use case.
 
 ## How it works
 
@@ -60,7 +63,8 @@ Use the following structure and instructions to create the guide for the code un
 
 ## Configuration options
 
-- If the code unit has configuration options, document them in a table detailing parameters, types, default values, and descriptions.
+- If the code unit has configuration options (e.g., settings, configuration objects), document them in a table detailing parameters, types, default values, and descriptions.
+- **Do NOT** list references of all attributes or methods of the classes. Exhaustive API references belong in auto-generated reference documentation, not in guides. Guides should focus on how to use the code unit.
 
 ## Advanced applications
 
@@ -73,4 +77,8 @@ Use the following structure and instructions to create the guide for the code un
 
 - Mention any limitations of the code unit, if known.
 
-```
+## Related samples
+
+- Link to relevant samples in the `contributing/` directory that demonstrate the use of this code unit.
+
+```

.github/workflows/analyze-releases-for-adk-docs-updates.yml

@@ -52,7 +52,9 @@ jobs:
         uses: actions/cache/restore@v4
         with:
           path: contributing/samples/adk_team/adk_documentation/adk_release_analyzer/sessions.db
-          key: analyzer-session-db
+          key: analyzer-session-db-${{ github.run_id }}-${{ github.run_attempt }}
+          restore-keys: |
+            analyzer-session-db-
 
       - name: Run Analyzing Script
         env:
@@ -88,4 +90,4 @@ jobs:
         uses: actions/cache/save@v4
         with:
           path: contributing/samples/adk_team/adk_documentation/adk_release_analyzer/sessions.db
-          key: analyzer-session-db
+          key: analyzer-session-db-${{ github.run_id }}-${{ github.run_attempt }}

.github/workflows/copybara-pr-handler.yml

@@ -17,6 +17,7 @@ on:
 
 jobs:
   close-imported-pr:
+    if: github.repository == 'google/adk-python'
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write

.github/workflows/issue-monitor.yml

@@ -30,6 +30,7 @@ on:
 
 jobs:
   sweep-spam:
+    if: github.repository == 'google/adk-python'
     runs-on: ubuntu-latest
     timeout-minutes: 120
     permissions:

.github/workflows/python-unit-tests.yml

@@ -39,5 +39,6 @@ jobs:
       run: |
         source .venv/bin/activate
         pytest tests/unittests \
+          -n auto \
           --ignore=tests/unittests/artifacts/test_artifact_service.py \
           --ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py

.pre-commit-config.yaml

@@ -11,6 +11,12 @@ repos:
     rev: v2.24.0
     hooks:
       - id: pyproject-fmt
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks:
+      - id: ruff
+        args: [--fix]
+        files: ^src/
   - repo: https://github.com/PyCQA/isort
     rev: 8.0.1
     hooks:

AGENTS.md

@@ -51,4 +51,4 @@ For detailed architecture patterns, component descriptions, and core interfaces,
 
 ## Development Setup
 
-The project uses `uv` for package management and Python 3.11+. Please refer to the **`adk-setup`** skill at `.agents/skills/adk-setup/SKILL.md` for detailed instructions.
+The project uses `uv` for package management and Python 3.10+. Please refer to the **`adk-setup`** skill at `.agents/skills/adk-setup/SKILL.md` for detailed instructions.