Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
144 lines (97 loc) · 3.29 KB

CONTRIBUTING.md

File metadata and controls

144 lines (97 loc) · 3.29 KB

Contributing to ARES

Thank you for your interest in contributing to the Agentic Research and Evaluation Suite!

Development Setup

Prerequisites

  • Python 3.12 or higher
  • uv package manager

Installing uv

If you don't have uv installed:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

Setting Up Your Environment

  1. Clone the repository:

    git clone https://github.com/withmartian/ares.git
cd ares

  2. Install all dependencies, including dev tools:

    uv sync --all-groups

    This installs the main dependencies plus development tools (pytest, ruff, pyright) and optional example dependencies.

Running Tests

uv run pytest

Tests are located in the src/ directory following the patterns test_*.py or *_test.py.

Code Quality

Linting

Check for code issues:

uv run ruff check

Formatting

Format your code:

uv run ruff format

Type Checking

Run static type analysis:

uv run pyright

Environment Variables

Some functionality may require environment variables for API keys or configuration. Check the codebase for specific requirements and create a .env file in the repository root as needed.

Pull Request Guidelines

Before submitting a PR:

  1. Run all checks locally:

    • Tests pass (uv run pytest)
    • Code is formatted (uv run ruff format)
    • No linting issues (uv run ruff check)
    • Type checks pass (uv run pyright)

  2. Write a clear PR description:

    • Explain what problem you're solving
    • Link to any related issues
    • Describe your approach if non-obvious

  3. Keep commits focused:

    • Each commit should represent a logical change
    • Use clear, descriptive commit messages

Code Style Guide

Import Conventions

Follow Google-style imports: always import modules, not individual classes or functions.

Examples:

# Good ✅
import ares
from ares import llms

request = llms.LLMRequest(messages=[...])
env = ares.make("sbv-mswea")

# Good for internal code ✅
from ares.llms import request
from ares.llms import response

req = request.LLMRequest(messages=[...])
resp = response.LLMResponse(data=[...], cost=0.0, usage=...)

# Avoid ❌
from ares.llms import LLMRequest, TextData
from ares.llms.request import LLMRequest

Rationale: Makes code more readable and explicit about where objects come from.

Comments

  • Comments should explain WHY, not WHAT: The code itself should be clear about what it does. Use comments to explain the reasoning, edge cases, or non-obvious decisions.
  • Comments explaining HOW: Only add these when the implementation is genuinely complex or uses a non-standard approach that might confuse future maintainers.
  • Follow existing patterns: Look at similar code in the repository to match the established style.

Docs

To build and view the docs locally:

uv sync --extra docs
cd docs && uv run --extra docs make html

and open the resulting docs/build/html/index.html file in your browser.

Questions?

If you have questions or need help, feel free to open an issue or reach out to the maintainers.