Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (76 loc) · 4.51 KB

CONTRIBUTING.md

File metadata and controls

109 lines (76 loc) · 4.51 KB

Contributing to AlphaAgent

Thank you for your interest in contributing to AlphaAgent! We welcome contributions that help improve this secure, CLI-first AI coding assistant.

Development Environment Setup

Prerequisites

  • Python >= 3.11
  • Git

Initial Setup

  1. Fork and clone the repository:

    git clone https://github.com/yourusername/AlphaAgent.git
cd AlphaAgent

  2. Create and activate a virtual environment:

    python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

  3. Install the package to development setup:

    pip install -e .

  4. Initialize the workspaces:

    alpha-agent init

Coding Standards

  • Code Style: We follow PEP 8 standard formatting in Python. Please run a formatter like black or ruff before making PRs.
  • Typing: Use strong typing with Python's standard typing module (e.g., list[str], str | None).
  • Security: Do not compromise the strict sandbox limits of the agent. The FilesystemGuard and CommandPolicy are vital.
  • Documentation: All functions, methods, and classes should have clear docstrings. Ensure changes are reflected in relevant .md documentation files.

Documentation layout

Adding Features

Adding a new slash command

  1. Step 1: Add an entry to the _SLASH_COMMANDS dict in alpha_agent/cli/chat.py (key = /name, value = description).
  2. Step 2: Implement the handler logic in ChatLoop._handle_slash_command.
  3. Step 3: If the command is registered but not yet implemented, use the standard stub: 
    self.console.print("[dim]/name - not yet implemented[/dim]")
  4. Step 4: Document the new command in docs/slash-commands.md matching the established format.

    Note: _SLASH_COMMANDS is the single source of truth that drives both the /help text output and the prompt_toolkit WordCompleter. Do not maintain separate lists!

diff_util.py - adding diff support to a new tool

When adding a tool that modifies files, you should display a unified diff instead of a generic "file written" message:

  • The is_binary_file check (from alpha_agent/tools/diff_util.py) must come before calling any read_text for the diff.
  • Pattern: Capture the before snapshot if it exists and is not binary. Mutate the file. Capture the after snapshot.
  • Pass the snapshots to print_unified_diff (from alpha_agent/cli/ui.py).
  • Note that print_unified_diff enforces a 50-line cap for display; longer diffs are truncated with an omission notice.

Personas - adding a new persona

  1. Add an entry to the PERSONAS dict in alpha_agent/cli/personas.py.
  2. Provide the description (shown in the /persona list) and prefix (injected directly before the agent's system prompt).
  3. If creating a default-like configuration, set prefix to an empty string (""), meaning the native AGENT.md remains unchanged by a persona prefix.

Running Tests

Security and sandbox isolation are paramount. The suite includes config/LLM mocks, CLI smoke tests, filesystem guard tests, and policy/audit coverage.

From the repository root (recommended):

python -m pytest tests/
  • Default run excludes tests marked integration (see pyproject.toml addopts). Unit and mocked tests must not require real API keys.
  • To run only integration tests (e.g. nightly jobs with secrets): python -m pytest -m integration
  • On some Windows setups, tests/test_security.py adjusts sys.stdout; if pytest reports capture teardown errors, use python -m pytest tests/ --capture=no.

You can still execute python tests/test_security.py directly for a quick guard/policy check.

Ensure all tests pass before submitting a Pull Request.

Pull Request Process

  1. Create a feature branch from main: 
    git checkout -b feature/your-feature-name
  2. Make your respective changes, ensuring the addition of related test code for the new capabilities.
  3. Commit your changes with descriptive and clean commit messages.
  4. Push your branch and open a Pull Request (PR).
  5. Ensure your PR description clearly describes the problem and solution. It will be reviewed by the maintainers.