Adk Style

# Documentation and Comments

## Public API Documentation

- **Clear Usage**: For public interfaces, explain the intended usage clearly, with concise examples.
- **Public Classes**: Explain all public attributes.
- **Public Methods/Functions**: Explain all arguments, return values, and raised exceptions.

## Internal Implementation Comments

- **Explain Why, Not What**: For internal code and private methods, explain **why**, not **what** — the code itself should be self-documenting.
- **Stale References**: Don't reference RFCs or design docs in source code (they become stale).


# File Organization

- One class per file in `workflow/`.
- Private modules prefixed with `_` (e.g., `_base_node.py`).
- Public API exported through `__init__.py`.
- Unit tests must be placed in the same folder hierarchy under `tests/unittests/` as the original file in `src/`.
- If a single source file has multiple test files (e.g. testing different classes or behaviors separately), use the source file name (without leading underscores or extension) as the prefix for the test file names.
  - Example: `src/google/adk/tools/environment/_tools.py` -> `tests/unittests/tools/environment/test_tools_edit_file.py`

## File Headers

Every source file must have:
1. Apache 2.0 license header.
2. `from __future__ import annotations`.
3. Standard library imports, then third-party, then relative.


# Formatting Style Guide

- 2-space indentation (never tabs).
- 80-character line limit.
- `pyink` formatter (Google-style).
- `isort` with Google profile for import sorting.
- Enforced automatically by pre-commit hooks (`isort`, `pyink`, `addlicense`, `mdformat`). Use the `adk-setup` skill to install and configure these tools.

## Running Formatter Manually

```bash
# Format only staged files (runs automatically on commit)
pre-commit run

# Format all changed files (staged + unstaged)
pre-commit run --files $(git diff --name-only HEAD)

# Format all files in the repo
pre-commit run --all-files
```


# Imports Style Guide

## General Rules

- **Source code** (`src/`): Use relative imports.
  `from ..agents.llm_agent import LlmAgent`
- **Tests** (`tests/`): Use absolute imports.
  `from google.adk.agents.llm_agent import LlmAgent`
- **Import from module**: Import from the module file, not from `__init__.py`.
  `from ..agents.llm_agent import LlmAgent` (not `from ..agents import LlmAgent`)
- **CLI package** (`cli/`):
  - Treat as an external package.
  - Use **relative imports** for files within the `cli/` package.
  - Use **absolute imports** for files outside of the `cli/` package.
  - **Dependency Direction**: Only `cli/` can import from the rest of the codebase. The other codebase must **STRICTLY NOT** import from `cli/`.

## TYPE_CHECKING Imports

Use `TYPE_CHECKING` for imports needed only by type hints to avoid circular imports at runtime:

```python
from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ..agents.invocation_context import InvocationContext
```

This works because `from __future__ import annotations` makes all annotations strings (deferred evaluation), so the import is never needed at runtime.


# Logging Style Guide

## General Rules

- **Lazy Evaluation**: Use lazy-evaluated `%`-based templates for logging to avoid overhead when the log level is not enabled.
  - **Good**: `logging.info("Processing item %s", item_id)`
  - **Bad**: `logging.info(f"Processing item {item_id}")`
- **Contextual Logging**: Leverage structured logging and trace IDs when available to correlate logs across operations.
- **No Secrets**: Never log sensitive information (API keys, user credentials, or PII).

## Log Levels

- **DEBUG**: Detailed information for diagnosing problems. Use generously in internal implementation but avoid cluttering production logs.
- **INFO**: Confirmation that things are working as expected (e.g., workflow started, node completed).
- **WARNING**: Indication that something unexpected happened or a problem might