docs/CONTRIBUTING.md

Contributing Guide

Welcome 👋

Thank you for your interest in contributing to the Multi-Agent System! This guide will help you get started.

Code of Conduct

• Be respectful and inclusive
• No harassment, discrimination, or offensive language
• Constructive feedback only

Getting Started

1. Fork and Clone

# Fork the repo on GitHub
git clone https://github.com/your-username/multi-agent-system.git
cd multi-agent-system
git remote add upstream https://github.com/jatingyass/multi-agent-system.git

2. Create a Branch

git checkout -b feature/my-feature
# or for fixes:
git checkout -b fix/issue-description

3. Set Up Development Environment

python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate.bat

pip install -r requirements-dev.txt

Making Changes

Code Style

• Use Black for formatting
• Follow PEP 8 guidelines
• Type hints are encouraged

# Format code
black backend/

# Check linting
ruff check backend/

# Type checking
mypy backend/

Writing Tests

• Add tests for new features
• Update tests for bug fixes
• Aim for >80% coverage

# Run tests
pytest

# With coverage
pytest --cov=backend

Documentation

• Update docstrings for functions/classes
• Add/update documentation in docs/ folder
• Update README if appropriate

def process_task(task: str) -> dict:
    """
    Process a task through the multi-agent system.
    
    Args:
        task: The task description
        
    Returns:
        dict: Task result with status and output
        
    Raises:
        ValueError: If task is empty
    """
    ...

Commit Guidelines

Use clear, descriptive commit messages:

feat: Add new memory retrieval strategy
fix: Correct agent routing in edge case
docs: Update API documentation
style: Format code with black
test: Add tests for memory agent
refactor: Simplify executor logic
chore: Update dependencies

git add .
git commit -m "feat: Add new memory retrieval strategy"

Pull Request Process

1. Update your branch

   git fetch upstream
   git rebase upstream/main
   

2. Push to your fork

   git push origin feature/my-feature
   

3. Open PR on GitHub

   • Clear title and description
   • Reference any related issues (#123)
   • Include screenshots for UI changes

4. Respond to feedback

   • Make requested changes
   • Push updates (auto-updates PR)
   • Re-request review

Types of Contributions

🐛 Bug Reports

1. Check if issue already exists
2. Create detailed bug report:
   • Steps to reproduce
   • Expected behavior
   • Actual behavior
   • System info

✨ Features

1. Open an issue to discuss first
2. Wait for maintainer feedback
3. Implement following guidelines
4. Submit PR

📚 Documentation

1. Fix typos or clarify explanations
2. Add examples or guides
3. Update API documentation
4. Submit PR

🔍 Code Review

1. Review open PRs
2. Provide constructive feedback
3. Suggest improvements
4. Test changes locally if possible

Development Tips

Running Locally with Docker

docker-compose up --build

Testing Agent Logic

# In tests/test_agents.py
from backend.agents.planner import plan_task
from backend.state.graph_state import create_initial_state

def test_planner_decomposition():
    state = create_initial_state("Test task")
    result = plan_task(state)
    assert "plan" in result
    assert len(result["plan"]) > 0

Debugging

# Use logging
from backend.core.logger import get_logger
log = get_logger(__name__)

log.debug("Debug message")
log.info("Info message")
log.error("Error message")

Project Structure

• backend/ — Python backend code
  • agents/ — Agent implementations
  • api/ — FastAPI application
  • core/ — Core utilities
  • memory/ — Memory management
  • tests/ — Unit tests
• frontend/ — React frontend
• docs/ — Documentation
• scripts/ — Setup and run scripts

Common Issues

Tests Failing

# Clear cache
pytest --cache-clear

# Verbose output
pytest -vv

# Stop on first failure
pytest -x

Import Errors

# Reinstall in development mode
pip install -e .

# Rebuild cache
python -m py_compile backend/

Environment Issues

# Recreate virtual environment
rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

Review Process

1. Maintainers will review your PR
2. Changes may be requested
3. Once approved, PR will be merged
4. Your contribution will be acknowledged!

Questions?

• Check existing issues and discussions
• Ask in PR comments
• Open a new discussion

License

By contributing, you agree your code will be licensed under the MIT License.

Thank you for contributing! 🎉