Skip to content

Contributing to AI Metacognition Toolkit

Thank you for your interest in contributing! This document provides guidelines for contributing to the project.

Code of Conduct

This project adheres to a Code of Conduct that all contributors are expected to follow.

How to Contribute

Reporting Bugs

  • Use the GitHub issue tracker
  • Check if the bug has already been reported
  • Include:
  • Python version
  • Package version
  • Minimal reproduction example
  • Expected vs actual behavior
  • Error messages and stack traces

Suggesting Enhancements

  • Use the GitHub issue tracker
  • Clearly describe the enhancement
  • Explain why it would be useful
  • Provide examples of how it would work

Pull Requests

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make your changes
  4. Add tests: Ensure >80% coverage
  5. Run tests: pytest tests/
  6. Update documentation: If changing API
  7. Commit: Use clear commit messages (no AI attribution per CLAUDE.md)
  8. Push: git push origin feature/my-feature
  9. Create Pull Request: With clear description

Development Setup

# Clone repository
git clone https://github.com/bassrehab/ai-metacognition-toolkit.git
cd ai-metacognition-toolkit

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src/ai_metacognition --cov-report=term-missing

Coding Standards

Style Guide

  • Follow PEP 8
  • Use Black for formatting: black src/ tests/
  • Use type hints throughout
  • Maximum line length: 100 characters

Documentation

  • Add docstrings to all public functions/classes
  • Use Google style docstrings
  • Include examples in docstrings
  • Update docs/ for new features

Testing

  • Write tests for all new features
  • Maintain >80% code coverage
  • Use pytest fixtures
  • Include edge cases and error handling tests

Commit Messages

Follow conventional commits format:

type(scope): description

- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- test: Test additions/changes
- refactor: Code refactoring
- style: Code style changes
- chore: Build/tooling changes

Example: feat(detector): add confidence threshold parameter

Important: Never include AI/Claude attribution in commits (see CLAUDE.md).

Documentation

Building Documentation

# Install documentation dependencies
pip install mkdocs mkdocs-material mkdocstrings[python]

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Documentation Structure

docs/
├── index.md                     # Home page
├── situational_awareness.md     # Detector guide
├── counterfactual_analysis.md   # Analyzer guide
├── observer_effect.md           # Monitor guide
├── examples.md                  # Code examples
├── api_reference.md             # API documentation
└── contributing.md              # This file

Testing Guidelines

Unit Tests

  • Test one thing per test
  • Use descriptive test names
  • Use fixtures from conftest.py
  • Test normal operation, edge cases, and errors

Integration Tests

  • Test complete workflows
  • Use realistic data
  • Verify end-to-end behavior

Running Tests

# All tests
pytest tests/

# Specific file
pytest tests/unit/test_situational_awareness.py

# With coverage
pytest tests/ --cov=src/ai_metacognition

# Verbose output
pytest tests/ -v

Review Process

  1. Automated checks must pass
  2. Code review by maintainer
  3. All comments addressed
  4. Tests passing
  5. Documentation updated

Release Process

Maintainers handle releases:

  1. Update CHANGELOG.md
  2. Bump version in pyproject.toml
  3. Create git tag
  4. Build and publish to PyPI

Questions?

Thank You!

Your contributions help make this project better for everyone. We appreciate your time and effort!