Contribution Guide

Contribution Guide#

We welcome contributions to Pantheon! This guide will help you get started with contributing to the project.

Getting Started#

Setting Up Development Environment#

  1. Fork the Repository

    Visit aristoteleo/PantheonOS and click “Fork”

  2. Clone Your Fork

    git clone https://github.com/YOUR_USERNAME/pantheon-agents.git
cd PantheonOS
git remote add upstream https://github.com/aristoteleo/PantheonOS.git

  3. Create Development Environment

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

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

# Install pre-commit hooks
pre-commit install

  4. Verify Installation

    # Run tests
pytest

# Check code style
black --check pantheon
isort --check-only pantheon
mypy pantheon

Development Workflow#

Creating a Feature Branch#

# Update main branch
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes
# ...

# Commit changes
git add .
git commit -m "feat: add new feature"

# Push to your fork
git push origin feature/your-feature-name

Commit Message Convention#

We follow conventional commits:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation changes

  • style: Code style changes (formatting, etc)

  • refactor: Code refactoring

  • test: Test additions or changes

  • chore: Build process or auxiliary tool changes

Examples:

feat: add support for Gemini models
fix: handle timeout in remote agents
docs: update team collaboration examples
test: add tests for SwarmCenter team

Code Standards#

Python Style Guide#

We follow PEP 8 with these additions:

  1. Type Hints: Use type hints for all public functions

    def process_data(
    data: List[Dict[str, Any]],
    options: Optional[ProcessOptions] = None
) -> ProcessResult:
    """Process data with given options."""
    pass

  2. Docstrings: Use Google-style docstrings

    def complex_function(param1: str, param2: int) -> dict:
    """Brief description of function.

    More detailed explanation if needed.

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

    Returns:
        Description of return value

    Raises:
        ValueError: When invalid input provided
    """
    pass

  3. Async/Await: Prefer async for I/O operations

    async def fetch_data(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

Testing Guidelines#

  1. Test Structure

    import pytest
from pantheon.agent import Agent

class TestAgent:
    @pytest.fixture
    def agent(self):
        return Agent("test", "Test agent")

    async def test_basic_functionality(self, agent):
        response = await agent.run([{"role": "user", "content": "test"}])
        assert response.messages

    async def test_error_handling(self, agent):
        with pytest.raises(ValueError):
            await agent.run([])

  2. Test Coverage: Aim for >80% coverage

    pytest --cov=pantheon --cov-report=html

  3. Integration Tests: Mark with appropriate decorators

    @pytest.mark.integration
@pytest.mark.requires_api_key
async def test_openai_integration():
    # Test that requires OpenAI API
    pass

Areas for Contribution#

High Priority Areas#

  1. Documentation - Add more examples - Improve API documentation - Create tutorials - Translate documentation

  2. Testing - Increase test coverage - Add integration tests - Performance benchmarks - Edge case testing

  3. Features - New team collaboration patterns - Additional toolsets - Enhanced memory systems - Better error handling

  4. Bug Fixes - Check GitHub issues - Fix reported problems - Improve error messages

Example Contributions#

Adding a New Toolset:

# pantheon/tools/new_tool.py
from pantheon.toolsets.utils.toolset import Toolset

class NewToolSet(Toolset):
    def __init__(self, name: str = "new_tools"):
        super().__init__(name)

    def get_tools(self):
        return [self.tool1, self.tool2]

    async def tool1(self, param: str) -> str:
        """Tool description."""
        # Implementation
        pass

Adding a New Team Pattern:

# pantheon/team/new_team.py
from pantheon.team.base import BaseTeam

class NewTeam(BaseTeam):
    def __init__(self, agents: List[Agent]):
        super().__init__(agents)

    async def run(self, messages: List[dict]) -> AgentResponse:
        # Team logic implementation
        pass

Submitting Changes#

Pull Request Process#

  1. Ensure Quality

    # Format code
black pantheon
isort pantheon

# Type check
mypy pantheon

# Run tests
pytest

# Check documentation
cd docs
make html

  2. Create Pull Request

    • Use descriptive title

    • Fill out PR template

    • Link related issues

    • Add screenshots if UI changes

  3. PR Description Template

    ## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement

## Testing
- [ ] Tests pass locally
- [ ] Added new tests
- [ ] Updated documentation

## Related Issues
Fixes #123

Review Process#

  1. Automated Checks: CI/CD runs tests and linting

  2. Code Review: Maintainers review code

  3. Feedback: Address review comments

  4. Merge: Once approved, changes are merged

Community Guidelines#

Code of Conduct#

  • Be respectful and inclusive

  • Welcome newcomers

  • Provide constructive feedback

  • Focus on what’s best for the community

Getting Help#

  • Discord: Join our community server

  • GitHub Discussions: Ask questions

  • Issues: Report bugs or request features

  • Email: pantheon-dev@example.com

Recognition#

Contributors are recognized in: - README.md contributors section - Release notes - Annual contributor report

License#

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT License).

Thank You!#

Thank you for contributing to Pantheon! Your efforts help make the project better for everyone.