Ak Dev Code Quality

Code Quality & Contribution Conventions

Code Formatting

Agent Kernel uses black for formatting and isort for import sorting.

Auto-format

# Format ak-py source and tests
make lint

# Format examples too
make lint-all

Check only (CI mode, no changes)

make lint-check       # ak-py only
make lint-check-all   # ak-py + examples

Auto-format a remote branch (CI)

To apply formatting on a remote branch without running the tools locally, trigger the Lint and Commit GitHub Actions workflow (.github/workflows/lint-fix.yml) manually from the Actions tab (workflow_dispatch). It takes two inputs:

• lint_target: which Makefile target to run — lint, lint-examples, or lint-all (default).
• branch: the branch to format and commit the changes to.

The workflow runs the selected target and pushes a chore: commit with any formatting changes back to the chosen branch. Protected branches (currently develop) are rejected before any changes are made.

Configuration

In ak-py/pyproject.toml:

[tool.black]
line-length = 150
target-version = ["py312"]

[tool.isort]
profile = "black"
line_length = 150

In example projects, line length is 120:

[tool.black]
line-length = 120
target-version = ["py312"]

Type Checking

cd ak-py
uv run mypy src/

Configuration:

[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true

Commit Convention

Use Conventional Commits format:

<type>: <short description>

Types

An optional scope narrows the type: type(scope): description, for example fix(ws): reconnect gateway after broker restart or chore(auto): sync skills/docs.

Examples

feat: add telegram messaging integration
fix: handle empty session in Redis store
docs: update deployment guide for Azure containerized
chore: bump openai-agents dependency to 0.6.5
refactor: extract common guardrail logic to base class
test: add unit tests for CosmosDB session store

Rules

• Use lowercase for commit type and description
• Keep the description under 72 characters
• Use imperative mood ("add feature" not "added feature")
• No period at the end
• Reference issue numbers when applicable: feat: add telegram integration (#123)
• PR titles follow the same format. .github/workflows/pr-title-check.yaml fails the PR otherwise, and because develop is squash-merge only the title becomes the commit subject

Pull Request Process

Base Branch

Branch from and target develop, not main — CI (.github/workflows/code-quality.yml) runs on pull requests against develop, and origin/HEAD points there.

Before Submitting

1. Run tests: cd ak-py && uv run pytest
2. Run linting: make lint-check-all

<!-- 3. **Run type checks**: `cd ak-py && uv run mypy src/` Enable after all mypy checks are passing -->

4. Ensure no regressions — all existing tests must pass

PR Guidelines

• One feature/fix per PR — keep PRs focused
• Include tests — new features must have tests
• Update docs — if the change affects user-facing behavior
• Add examples — for new features, add or update examples
• Conventional title: type: description or type(scope): description using one of the commit types above; the PR Title Check workflow blocks anything else
• Fill in the PR template — description, type of change, testing done

Review Workflow

• Copilot review is automatic for collaborators: .github/workflows/copilot-review-request.yaml requests a Copilot code review when a collaborator's PR is opened, reopened, or marked ready for review (bot-authored PRs excluded). Collaborators never need to request it by hand. PRs from outside contributors are not requested automatically; a maintainer runs the workflow from the Actions tab with the PR number after a first read.
• Reviewed label: maintainers add Reviewed once they have gone through a PR. .github/workflows/reviewed-label-reset.yaml removes it on every new push so the PR reappears in is:pr is:open -label:Reviewed. Contributors should not touch the label.

PR Types

• Core changes: Modifications to ak-py/src/agentkernel/core/
• Integration additions: New messaging platforms, framework adapters
• Documentation: Updates to docs/, README files
• Testing: New or improved tests
• Community support: Bug reports, feature suggestions

Version Management

Version Bumping

Handled by publish.yaml workflow. This updates:

This updates:

• ak-py/pyproject.toml version field
• Terraform module versions
• Example dependency versions

Version Locations

The version appears in:

• ak-py/pyproject.toml → version = "x.y.z"
• Terraform modules version fields in examples
• agentkernel dependency version constraints in example pyproject.toml files

Development Setup

Prerequisites

• Python 3.12–3.13.x
• uv package manager
• Git
• Make

Setup

git clone https://github.com/yaalalabs/agent-kernel.git
cd agent-kernel
make dev-setup                # Installs pyenv, Python 3.12, uv, then syncs ak-py venv
# or directly: ./scripts/dev-setup.sh

Alternatively, set things up manually:

cd agent-kernel/ak-py
./build.sh                    # Creates venv, installs deps

Running Examples

cd examples/cli/openai
./build.sh
uv run demo.py

Running Tests

cd examples/cli/openai
./build.sh
uv run pytest -s

File Organization Conventions

• Source: ak-py/src/agentkernel/ — all package source code
• Tests: ak-py/tests/ — unit tests
• Examples: examples/<mode>/<framework>/ — self-contained demo projects
• Docs: docs/docs/ — Docusaurus documentation
• Scripts: scripts/ — CI/CD and maintenance scripts
• Terraform: ak-deployment/ — Terraform modules