Contributing¶

Thank you for your interest in contributing to the NHRA Game Theory toolkit! This guide will help you get started.

Development Setup¶

Prerequisites¶

Python 3.10, 3.11, 3.12, or 3.13
Poetry for dependency management
Git

Initial Setup¶

# Clone the repository
git clone https://github.com/edithatogo/nhra_game.git
cd nhra_game

# Install dependencies (including dev tools)
poetry install --with dev

# Activate the virtual environment
poetry shell

# Install pre-commit hooks
pre-commit install

Code Quality¶

We enforce strict code quality standards. All contributions must pass:

Linting & Formatting¶

# Run ruff linter
poetry run ruff check src tests

# Run ruff formatter
poetry run ruff format src tests

# Auto-fix issues
poetry run ruff check src tests --fix

Type Checking¶

# Run mypy in strict mode
poetry run mypy --strict src/nhra_gt

Testing¶

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/nhra_gt --cov-report=html

Pre-commit¶

All checks run automatically on commit:

# Run all pre-commit hooks manually
pre-commit run --all-files

Pull Request Process¶

Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Make changes following code quality standards
Add tests for new functionality
Update documentation if needed
Commit with Conventional Commits:
feat: for new features
fix: for bug fixes
docs: for documentation
refactor: for code refactoring
test: for test additions/changes
ci: for CI/CD changes
Push and create a Pull Request

Code Style¶

Python¶

Follow PEP 8
Use type hints everywhere
Maximum line length: 100 characters
Use docstrings for all public functions/classes

Docstrings¶

Use Google-style docstrings:

def example_function(param1: str, param2: int) -> bool:
    """Short description of the function.

    Longer description if needed, explaining the purpose
    and any important details.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        Description of return value.

    Raises:
        ValueError: When param2 is negative.
    """
    pass

Adding New Games¶

To add a new stage game:

Define the game in src/nhra_gt/subgames/games.py:

def new_game(gp: GameParams) -> TwoPlayerGame:
    """Description of the new game."""
    # Build payoff matrices
    u_row = np.array([[...], [...]])
    u_col = np.array([[...], [...]])
    return TwoPlayerGame(
        u_row=u_row,
        u_col=u_col,
        row_actions=("A", "B"),
        col_actions=("A", "B")
    )

Add to agents in src/nhra_gt/agents/base.py if the game should be played in simulation
Document the game in docs_mkdocs/guides/models.md
Add tests in tests/

Questions?¶

Open an issue on GitHub or check the documentation.