Contributing to MLAI

Thank you for your interest in contributing to MLAI! This guide will help you get started.

Project Philosophy

MLAI follows the principles outlined in our Project Tenets. Before contributing, please familiarize yourself with these guiding principles:

  1. Clarity Over Cleverness: Code should be easy to understand

  2. Mathematical Transparency: Mathematical concepts should be explicit

  3. Educational Focus: Every contribution should serve a pedagogical purpose

  4. Good Python Practices: Follow PEP 8 and modern Python conventions

  5. Reproducibility: Examples should be runnable end-to-end

  6. Inclusivity: Documentation should be accessible to diverse audiences

  7. Open Science: Encourage sharing and collaboration

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally

  3. Create a virtual environment: .. code-block:: bash

    python -m venv venv source venv/bin/activate # On Windows: venvScriptsactivate

  4. Install dependencies: .. code-block:: bash

    pip install -e . pip install -r requirements-dev.txt # If available

Development Workflow

  1. Check existing issues and CIPs: Look at the Code Improvement Proposals (CIPs) and Project Backlog

  2. Create a feature branch: git checkout -b feature/your-feature-name

  3. Make your changes: Follow the coding standards below

  4. Test your changes: Run the test suite (when available)

  5. Update documentation: Add or update docstrings and documentation

  6. Submit a pull request: Include a clear description of your changes

Coding Standards

  • Style: Follow PEP 8 and PEP 257

  • Type hints: Use type hints where they improve clarity

  • Docstrings: Use NumPy or Google docstring format

  • Mathematical notation: Include mathematical equations in docstrings

  • Examples: Provide working examples in docstrings

Example docstring:

def gaussian_kernel(x1, x2, lengthscale=1.0):
    """
    Compute the Gaussian (RBF) kernel between two points.

    The Gaussian kernel is defined as:

    .. math::
       k(x_1, x_2) = \exp\left(-\frac{\|x_1 - x_2\|^2}{2\ell^2}\right)

    where :math:`\ell` is the lengthscale parameter.

    Parameters
    ----------
    x1 : array-like
        First input point
    x2 : array-like
        Second input point
    lengthscale : float, default=1.0
        Lengthscale parameter :math:`\ell`

    Returns
    -------
    float
        Kernel value

    Examples
    --------
    >>> gaussian_kernel([0], [1], lengthscale=1.0)
    0.6065306597126334
    """
    pass

Testing

When the test framework is implemented (see CIP-0002: Comprehensive Test Framework with pytest), please:

  • Write tests for new functionality

  • Ensure all tests pass

  • Maintain or improve test coverage

  • Include property-based tests for mathematical functions

Documentation

  • Update docstrings for any functions you modify

  • Add examples to the tutorials if relevant

  • Update this contributing guide if needed

  • Follow the documentation style guide

Submitting Changes

  1. Write a clear commit message following conventional commits

  2. Reference related issues or CIPs in your commit message

  3. Provide a detailed pull request description

  4. Include examples of how your changes work

  5. Link to relevant documentation or discussions

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful and constructive in all interactions.

Questions?

If you have questions about contributing:

Thank you for contributing to MLAI!