Skip to content

Commit 765ab15

Browse files
aimenhamzi01-dotaimenhamzi01-dot
authored
Merge branch 'main' into main
2 parents ce2753a + 844cd36 commit 765ab15

85 files changed

Lines changed: 4332 additions & 1939 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/adk-unit-design/SKILL.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
name: adk-unit-design
3+
description: Creates or updates code unit design documents for source code documentation.
4+
---
5+
6+
# ADK Code Unit Design
7+
8+
This skill creates or updates a detailed software engineering design document for new or updated code file or specified code unit. The design document it generates is meant to explain the code to a developer who wants to modify or extend the code unit as part of the ADK development framework. Similar to a *unit test*, a *unit design* provides a generated software engineering design based on the *actual, implemented code* rather than any proposed code design or proposed software architecture.
9+
10+
## Input
11+
12+
- Code files containing new functionality
13+
- Names of new methods and classes (optional)
14+
- Code files for base classes or interfaces that the new functionality depends on (optional)
15+
- Code unit tests (optional)
16+
- Example code files (optional)
17+
18+
## Analysis
19+
20+
- Review specified code files for changes and named methods to determine:
21+
- Purpose and intended use of the new or updated code units
22+
- Any data flows handled by the new or updated code units
23+
- Dependencies required by the new or updated code units
24+
- Approaches for extending or customizing the code unit to add new capabilities
25+
- Classes that depend on the new or updated code units
26+
- Operational limitations of the new or updated code units
27+
28+
## Output
29+
30+
- Look for an existing design document in the `/docs/design/***` directory of this repository.
31+
- If a design already exists, update the existing design incrementally and prioritize preserving the previous content as much as possible.
32+
- If no design document exists, create a design file for the new code unit in the `/docs/design/***` 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 design document in the location `/docs/design/topic/function/class/index.md`.
33+
- Any links to local code files should be translated to URL links to the `google/adk-python` repository on GitHub. For example, if the local code unit path is `***/adk-python/topic/function/class.ext#L93`, the URL to the code file should be `https://github.com/google/adk-python/blob/main/topic/function/class.ext#L93`.
34+
35+
### Design document structure and content
36+
37+
Use the following structure and instructions to create the design document for the code unit:
38+
39+
```
40+
# (name of code unit or code file) - Code Unit Design
41+
42+
- 2-sentence summary of the code unit
43+
44+
## Introduction
45+
46+
- Paragraph(s) explaining:
47+
- The purpose and application of the code unit, including intended use cases
48+
- Developer problems solved by this code unit
49+
- Agent capabilities enabled by this code unit
50+
51+
## High-level architecture
52+
53+
- Describe the software architecture of this code unit and how it fits into the larger ADK framework
54+
- Explain general execution flow of this code unit
55+
- Describe any data flows handled by the code unit including inputs and outputs
56+
- Explain any cross-class dependencies of the code unit, including upstream dependencies and downstream dependencies
57+
58+
### Extension points
59+
60+
- Describe how the code unit could be extended or customized to add new features or capabilities
61+
- Note specific parts of the code unit that are designed to be extended or customized, including:
62+
- Abstract classes
63+
- Interfaces
64+
- Hooks
65+
- Callbacks
66+
- Configurable parameters
67+
- Plugin architecture
68+
- Other extension points
69+
70+
### Extension constraints
71+
72+
- Describe what parts of the code unit should not be modified, based on:
73+
- architectural constraints
74+
- implementation limitations
75+
- cross-class dependencies
76+
- other constraints
77+
78+
## Limitations
79+
80+
- Mention any limitations of the code unit, if known, such as:
81+
- input constraints
82+
- data structure constraints
83+
- output constraints
84+
- performance limitations
85+
- memory limitations
86+
- other limitations
87+
88+
```

‎.github/workflows/check-file-contents.yml‎

Lines changed: 0 additions & 150 deletions
This file was deleted.

‎.github/workflows/continuous-integration.yml‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,3 +148,129 @@ jobs:
148148
-n auto \
149149
--ignore=tests/unittests/artifacts/test_artifact_service.py \
150150
--ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py
151+
152+
# 4. Custom file content compliance checks (PR only)
153+
compliance-check:
154+
name: File Content Compliance
155+
runs-on: ubuntu-latest
156+
if: github.event_name == 'pull_request'
157+
steps:
158+
- name: Checkout Code
159+
uses: actions/checkout@v6
160+
with:
161+
# Fetch full history (depth: 0) instead of shallow clone (depth: 2) to ensure
162+
# git diff origin/${base_ref}...HEAD can reliably find the merge base,
163+
# preventing fatal git errors on deep PRs or when the target branch has progressed.
164+
fetch-depth: 0
165+
166+
- name: Check for logger pattern in all changed Python files
167+
run: |
168+
git fetch origin ${GITHUB_BASE_REF}
169+
CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' || true)
170+
if [ -n "$CHANGED_FILES" ]; then
171+
echo "Changed Python files to check:"
172+
echo "$CHANGED_FILES"
173+
echo ""
174+
175+
# Check for 'logger = logging.getLogger(__name__)' in changed .py files.
176+
set +e
177+
FILES_WITH_FORBIDDEN_LOGGER=$(grep -lE 'logger = logging\.getLogger\(__name__\)' $CHANGED_FILES)
178+
GREP_EXIT_CODE=$?
179+
set -e
180+
181+
if [ $GREP_EXIT_CODE -eq 0 ]; then
182+
echo "❌ Found forbidden use of 'logger = logging.getLogger(__name__)'. Please use 'logger = logging.getLogger('google_adk.' + __name__)' instead."
183+
echo "The following files contain the forbidden pattern:"
184+
echo "$FILES_WITH_FORBIDDEN_LOGGER"
185+
exit 1
186+
elif [ $GREP_EXIT_CODE -eq 1 ]; then
187+
echo "✅ No instances of 'logger = logging.getLogger(__name__)' found in changed Python files."
188+
fi
189+
else
190+
echo "✅ No relevant Python files found."
191+
fi
192+
193+
- name: Check for import pattern in certain changed Python files
194+
run: |
195+
git fetch origin ${GITHUB_BASE_REF}
196+
CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' | grep -v -E '__init__.py$|version.py$|tests/.*|contributing/samples/' || true)
197+
if [ -n "$CHANGED_FILES" ]; then
198+
echo "Changed Python files to check:"
199+
echo "$CHANGED_FILES"
200+
echo ""
201+
202+
# Use grep -L to find files that DO NOT contain the pattern.
203+
FILES_MISSING_IMPORT=$(grep -L 'from __future__ import annotations' $CHANGED_FILES || true)
204+
205+
if [ -z "$FILES_MISSING_IMPORT" ]; then
206+
echo "✅ All modified Python files include 'from __future__ import annotations'."
207+
exit 0
208+
else
209+
echo "❌ The following files are missing 'from __future__ import annotations':"
210+
echo "$FILES_MISSING_IMPORT"
211+
echo "This import is required to allow forward references in type annotations without quotes."
212+
exit 1
213+
fi
214+
else
215+
echo "✅ No relevant Python files found."
216+
fi
217+
218+
- name: Check for import from cli package in certain changed Python files
219+
run: |
220+
git fetch origin ${GITHUB_BASE_REF}
221+
CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' | grep -v -E 'cli/.*|src/google/adk/tools/apihub_tool/apihub_toolset.py|tests/.*|contributing/samples/' || true)
222+
if [ -n "$CHANGED_FILES" ]; then
223+
echo "Changed Python files to check:"
224+
echo "$CHANGED_FILES"
225+
echo ""
226+
227+
set +e
228+
FILES_WITH_FORBIDDEN_IMPORT=$(grep -lE '^from.*\bcli\b.*import.*$' $CHANGED_FILES)
229+
GREP_EXIT_CODE=$?
230+
set -e
231+
232+
if [[ $GREP_EXIT_CODE -eq 0 ]]; then
233+
echo "❌ Do not import from the cli package outside of the cli package. If you need to reuse the code elsewhere, please move the code outside of the cli package."
234+
echo "The following files contain the forbidden pattern:"
235+
echo "$FILES_WITH_FORBIDDEN_IMPORT"
236+
exit 1
237+
else
238+
echo "✅ No instances of importing from the cli package found in relevant changed Python files."
239+
fi
240+
else
241+
echo "✅ No relevant Python files found."
242+
fi
243+
244+
- name: Check for hardcoded googleapis.com endpoints
245+
run: |
246+
git fetch origin ${GITHUB_BASE_REF}
247+
CHANGED_FILES=$(git diff --diff-filter=ACMR --name-only origin/${GITHUB_BASE_REF}...HEAD | grep -E '\.py$' || true)
248+
if [ -n "$CHANGED_FILES" ]; then
249+
echo "Checking for hardcoded endpoints in: $CHANGED_FILES"
250+
251+
# 1. Identify files containing any googleapis.com URL.
252+
set +e
253+
FILES_WITH_ENDPOINTS=$(grep -lE 'https?://[a-zA-Z0-9.-]+\.googleapis\.com' $CHANGED_FILES)
254+
255+
# 2. From those, identify files that are MISSING the required mTLS version.
256+
if [ -n "$FILES_WITH_ENDPOINTS" ]; then
257+
FILES_MISSING_MTLS=$(grep -L '.mtls.googleapis.com' $FILES_WITH_ENDPOINTS)
258+
fi
259+
set -e
260+
261+
if [ -n "$FILES_MISSING_MTLS" ]; then
262+
echo "❌ Found hardcoded googleapis.com endpoints without mTLS support."
263+
echo "The following files must define both standard and mTLS (.mtls.googleapis.com) endpoints"
264+
echo "to support dynamic endpoint selection as required by security policy:"
265+
echo "$FILES_MISSING_MTLS"
266+
echo ""
267+
echo "To fix this, please follow these steps:"
268+
echo "1. Initialize an AuthorizedSession with your credentials."
269+
echo "2. Use 'mtls.has_default_client_cert_source() from google-auth' to check for available client certificates."
270+
echo "3. If certificates are present, use 'session.configure_mtls_channel()'."
271+
echo "4. Dynamically select the '.mtls.' variant of the endpoint when mTLS is active."
272+
exit 1
273+
else
274+
echo "✅ All hardcoded endpoints have corresponding mTLS definitions or no endpoints found."
275+
fi
276+
fi

0 commit comments

Comments
 (0)