Skip to content

AGENTS.md

Latest commit

 

History

History
197 lines (150 loc) · 7.93 KB

AGENTS.md

File metadata and controls

197 lines (150 loc) · 7.93 KB
Raw

Who This Is For

  • AI agents: Automate repository tasks with minimal context
  • Contributors: Humans using AI assistants or working directly
  • Maintainers: Ensure assistants follow project conventions and CI rules

Agent Behavior Policy

AI agents should:

  • Make atomic, minimal, and reversible changes.
  • Prefer local analysis (uv run, make verify, pytest) before proposing commits.
  • NEVER modify configuration, CI/CD, or release automation unless explicitly requested.
  • Avoid non-deterministic code or random seeds without fixtures.
  • Use AGENTS.md and Makefile as the source of truth for development commands.

Agents must NOT:

  • Bypass tests or linters
  • Introduce dependencies without updating pyproject.toml
  • Generate or commit large autogenerated files

Context Awareness

Before writing code, agents should:

  • Read docstrings and existing test cases for pattern alignment
  • Match import patterns from neighboring files
  • Preserve existing logging and error-handling conventions

Repository Map

.github/                         # GitHub actions for CI/CD
CHANGELOG/                       # Release changelogs
docs/                            # Kubeflow SDK documentation
examples/                        # Kubeflow SDK examples
hack/                            # Scripts to manage CI/CD and installation
proposals/                       # Kubeflow Enhancement Proposals (KEPs)
test/                            # Top-level end-to-end tests
kubeflow/                        # Main Python package
├── common/                        # Shared utilities, types, and constants across all projects
│
├── trainer/                       # Kubeflow Trainer
│   ├── api/                         # TrainerClient - main user interface
│   ├── backends/                    # Execution backend implementations
│   │   ├── kubernetes/                # Kubernetes backend
│   │   ├── container/                 # Container backend for local development
│   │   │   └── adapters/                # Docker & Podman adapter implementations
│   │   └── localprocess/              # Subprocess backend for quick prototyping
│   ├── constants/                   # Common trainer constants and defaults
│   ├── options/                     # Backend configuration options (KubernetesOptions, etc.)
│   ├── types/                       # Common trainer types (e.g. TrainJob, CustomTrainer, BuiltinTrainer)
│   └── test/                        # Shared test fixtures (common.py)
│
├── optimizer/                     # Kubeflow Optimizer
│   ├── api/                         # OptimizerClient - main user interface
│   ├── backends/                    # Execution backend implementations
│   │   └── kubernetes/                # Kubernetes backend
│   ├── types/                       # Common optimizer types (e.g. OptimizationJob, Search)
│   └── constants/                   # Common optimizer constants and defaults
│
├── spark/                         # Kubeflow Spark
│   ├── api/                         # SparkClient - main user interface
│   ├── backends/                    # Execution backend implementations
│   │   └── kubernetes/                # Kubernetes backend
│   └── types/                       # Spark types and options
│
└── hub/                           # Kubeflow Hub
    ├── api/                         # ModelRegistryClient - main user interface
    └── types/                       # Hub types

Environment & Tooling

  • Package manager: uv (creates .venv automatically via targets)
  • Lint/format: ruff (isort integrated)
  • Tests: pytest with coverage
  • Build: Hatchling (optional uv build)
  • Pre-commit: Config provided and enforced in CI

Commands

Setup:

make install-dev              # Install uv, create .venv, sync deps

Verify (CI parity):

make verify                   # Runs ruff check --show-fixes and ruff format --check

Testing:

make test-python              # All unit tests + coverage (HTML by default)
make test-python report=xml   # XML coverage report
uv run pytest -q kubeflow/trainer/utils/utils_test.py                    # One file
uv run pytest -q kubeflow/trainer/utils/utils_test.py::test_name -k "pattern"  # One test
uv run coverage run -m pytest <path> && uv run coverage report          # Ad-hoc coverage

Local lint/format:

uv run ruff check --fix .                    # Fix lint issues (all files)
uv run ruff format kubeflow                  # Format kubeflow package
uv run ruff check path/to/file.py            # Lint single file
uv run ruff format path/to/file.py           # Format single file

Type checking:

uv run ty check kubeflow/hub                 # Run type checker
uv run ty check path/to/file.py              # Type-check single file

Pre-commit:

uv run pre-commit install                    # Install hooks
uv run pre-commit run --all-files           # Run all hooks

Development Workflow for AI Agents

Preferred commands: use uv run ... to ensure tool consistency and .venv usage

Before making changes:

  1. Read existing code patterns and docstrings for alignment
  2. Follow the Core Development Principles below
  3. Run validation commands before proposing changes

Validation before proposing changes:

  • Lint/format: make verify
  • Tests: make test-python or targeted pytest invocations
  • Type checking: uv run ty check kubeflow/hub

Commit/PR hygiene:

  • Follow Conventional Commits in titles and messages
  • Include rationale ("why") in commit messages/PR descriptions
  • Do not push secrets or change git config
  • Scope discipline: only modify files relevant to the task; keep diffs minimal

Core Development Principles

1. Maintain Stable Public Interfaces ⚠️ CRITICAL

  • Always preserve function signatures, argument positions, and names for exported/public methods
  • Check if the function/class is exported in __init__.py before changing public APIs
  • Look for existing usage patterns in tests and examples
  • Use keyword-only arguments for new parameters: *, new_param: str = "default"
  • Mark experimental features clearly with docstring warnings

2. Code Quality Standards

  • All Python code MUST include type hints and return types
  • Line length 100, Python 3.10 target, double quotes, spaces indent
  • Imports: isort via ruff; first-party is kubeflow; prefer absolute imports
  • Naming: pep8-naming; functions/vars snake_case, classes PascalCase, constants UPPER_SNAKE_CASE; prefix private with _
  • Use descriptive, self-explanatory variable names
  • Break up complex functions (>20 lines) into smaller, focused functions where it makes sense
  • Follow existing patterns in the codebase you're modifying

3. Testing Requirements

  • Every new feature or bugfix MUST be covered by unit tests
  • Unit tests: kubeflow/trainer/**/*_test.py (no network calls allowed)
  • Use pytest with TestCase dataclass for parametrized tests (see kubeflow/trainer/backends/kubernetes/backend_test.py for the reference pattern)
  • See kubeflow/trainer/test/common.py for fixtures and patterns

4. Security

  • No eval(), exec(), or pickle on user-controlled input
  • Proper exception handling (no bare except:) with descriptive error messages
  • Remove unreachable/commented code before committing
  • Ensure proper resource cleanup (file handles, connections)
  • No secrets in code, logs, or examples

5. Documentation Standards

  • Use Google-style docstrings with Args section for all public functions
  • Types go in function signatures, NOT in docstrings
  • Focus on "why" rather than "what" in descriptions
  • Document all parameters, return values, and exceptions
  • Use Pydantic v2 models in kubeflow.trainer.types for schemas