Contributing Guidelines

Thank you for your interest in contributing to ai_nn_controller!

Getting Started

Fork the repository

Clone your fork:

git clone https://github.com/YOUR_USERNAME/ai_nn_controller.git
cd ai_nn_controller

Set up the development environment:

python -m venv venv
source venv/bin/activate
cd controller_components/ai_nn_controller
pip install -e ".[dev]"

Create a branch for your changes:
```
git checkout -b feature/my-feature
```

Code Style

We follow these coding standards:

PEP 8 for Python code style
Black for code formatting
isort for import sorting
Type hints for function signatures

Run formatters before committing:

black controller_components/
isort controller_components/

Documentation

All public functions and classes should have docstrings

Use Google-style docstrings:

def my_function(param1: int, param2: str) -> bool:
    """
    Brief description.

    Longer description if needed.

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

    Returns:
        Description of return value

    Raises:
        ValueError: When something is wrong
    """

Update documentation when changing functionality
Add examples for new features

Testing

Write tests for new features
Ensure existing tests pass:
```
pytest controller_components/
```

Test with Docker:

docker compose up -d
# Run your tests
docker compose down

Pull Request Process

Update documentation for any changed functionality
Add tests for new features
Ensure all tests pass
Update the CHANGELOG if applicable
Create a pull request with a clear description

Commit Messages

Use clear, descriptive commit messages:

Start with a verb (Add, Fix, Update, Remove)
Keep the first line under 50 characters
Add details in the body if needed

Good examples:

Add SET_TILT command handler

Fix measurement routing for multi-node apps

Update documentation for MCP integration

Reporting Issues

When reporting issues, include:

Python version
Docker version (if applicable)
Steps to reproduce
Expected vs actual behavior
Relevant log output

Feature Requests

For feature requests:

Describe the use case
Explain the proposed solution
Consider alternatives

Questions

Check existing documentation first
Search existing issues
Open a new issue with the “question” label