Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (96 loc) · 3.32 KB

CONTRIBUTING.md

File metadata and controls

134 lines (96 loc) · 3.32 KB
Raw

Contributing to FrontierAgent

Thank you for your interest in contributing to FrontierAgent! This document provides guidelines and instructions for contributing.

Getting Started

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/FrontierAgent.git
cd FrontierAgent
  3. Install dependencies: 
    pip install uv
uv sync --all-extras
  4. Create a feature branch: 
    git checkout -b feature/your-feature-name

Development Setup

Prerequisites

  • Python ≥ 3.12
  • uv (recommended) or pip

Fully loaded environment

The quick start in the README installs the lightweight terminal runtime. Development wants every optional extra present up front:

uv sync --frozen \
  --extra sandbox \
  --extra document-readers \
  --extra eval \
  --extra dev

uv run frontier-agent --no-tui -p "say hello"

Linux uses the workspace-local native runtime for that command. Pass --bwrap or --docker when development requires an OS isolation boundary; --no-sandbox deliberately uses the real home directory and host caches as well.

To build and run the container image, see Run FrontierAgent in Docker.

Running Tests

# Fast checks for TUI/CLI changes
uv run pytest apodex/tests -q

# Workflow and framework tests
uv run pytest tests -q

# Everything, plus lint
uv run pytest -q
uv run ruff check .

Debugging a session

Line mode removes full-screen rendering from the equation:

uv run frontier-agent --no-tui --mode agent_team --cwd /path/to/project

Inside the session, /log prints its trace location. After a failure, inspect:

tail -f /path/to/project/.apodex/runs/<session-id>/engine.log
python -m json.tool /path/to/project/.apodex/runs/<session-id>/session.json

On macOS, rebuild after Docker or runtime changes:

docker build -t apodex:local .
uv run frontier-agent --docker --no-tui --mode agent_team --cwd /path/to/project

For benchmark debugging, keep both question and team concurrency small and write each run to a dedicated result directory.

Code Quality

We use Ruff for linting and formatting:

uv run ruff check .
uv run ruff format .

Pre-flight Checks

Before submitting, run the pre-flight validation:

uv run python tools/preflight.py
uv run python tools/import_smoke.py

Submitting Changes

  1. Ensure all tests pass and pre-flight checks are clean.
  2. Write clear, concise commit messages.
  3. Push to your fork and open a Pull Request against main.
  4. Describe what changed and why in the PR description.

Reporting Issues

  • Use GitHub Issues to report bugs or request features.
  • Include steps to reproduce, expected behavior, and actual behavior.
  • Attach relevant logs or error messages.

Code Style

  • Follow existing conventions in the codebase.
  • Add docstrings to public functions and classes.
  • Use type annotations throughout.
  • Keep lines ≤ 100 characters (configured in pyproject.toml).

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.