Skip to content

DEVELOPER_GUIDE.md

Latest commit

 

History

History
159 lines (117 loc) · 3.57 KB

DEVELOPER_GUIDE.md

File metadata and controls

159 lines (117 loc) · 3.57 KB
Raw

Developer Guide

This guide provides essential information for developers working on the Agent Kernel project.

Table of Contents

Prerequisites

Before you begin development, ensure you have the following installed:

  • Python 3.12 or higher
  • uv - Fast Python package installer and resolver
  • Git
  • Make

Setup Your Development Environment

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/yaalalabs/agent-kernel.git
cd agent-kernel

  3. Add the upstream repository:

    git remote add upstream https://github.com/yaalalabs/agent-kernel.git

  4. Create a branch for your changes:

    git checkout -b feature/your-feature-name

Development

  1. Run the dev setup script from the repo root to install prerequisites (pyenv, Python 3.12, uv) and sync the ak-py virtual environment:

    make dev-setup

    or directly:

    ./scripts/dev-setup.sh

    Alternatively, set things up manually:

    cd ak-py
./build.sh

Makefile Commands

The project includes a Makefile with several useful commands for code formatting and quality checks. All commands should be run from the root directory of the project.

Available Commands

To see all available Makefile commands:

make help

Code Quality

Formatting Standards

Agent Kernel uses the following tools to maintain code quality:

  • black: Opinionated code formatter
  • isort: Import statement organizer

Pre-commit Workflow

Before committing code, run:

make lint-check-all

This ensures your code meets the project's formatting standards without making changes. If issues are found, run:

make lint-all

to automatically fix formatting issues.

Contributing

Development Workflow

  1. Create a feature branch

    git checkout -b feature/your-feature-name

  2. Make your changes

    • Write code following the project's conventions
    • Add tests for new functionality

  3. Verify formatting

    make lint-check-all

  4. Format your code

    make lint-all

  5. Run tests

    cd ak-py
uv run pytest

  6. Commit your changes

    git add .
git commit -m "feat: describe your changes"

  7. Push to your branch

    git push origin feature/your-feature-name

Commit Message Convention

Follow conventional commit format:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • chore: - Maintenance tasks
  • refactor: - Code refactoring
  • test: - Test additions or modifications

Code Review

  • Ensure all formatting checks pass
  • Add appropriate tests
  • Ensure all CI tests pass
  • Update documentation if needed
  • Request review from maintainers

Additional Resources

  • Main README - Project overview and usage
  • AGENTS.md - Guidance for AI coding agents contributing to this repo (architecture pointers, agent-specific gotchas)
  • Documentation Setup - Setting up the documentation site
  • Examples - Sample implementations
  • Use Cases - End-to-end agents built from SPEC.md using Agent Kernel skills