MARSYS Logo
MARSYSFramework

Navigation

Getting StartedConceptsAPI ReferenceGuides
GitHub

Contributing

Join the MARSYS community and help build the future of multi-agent AI systems.

Ways to Contribute

Report Issues

Bug reports, performance issues, documentation gaps, and feature requests

Code Contributions

Bug fixes, new features, performance optimizations, and refactoring

Documentation

Fix typos, improve explanations, add examples, and write tutorials

Testing

Write unit tests, integration tests, test edge cases, and report failures

Quick Start

1. Fork & Clone

# Fork on GitHub, then:
git clone https://github.com/yourusername/marsys.git
cd marsys


# Add upstream remote
git remote add upstream https://github.com/rezaho/MARSYS.git

2. Set Up 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

3. Create Feature Branch

# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main


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

4. Make Changes

# Make your changes, add tests, update documentation


# Run tests
pytest tests/


# Check code style
black src/ tests/
isort src/ tests/
flake8 src/ tests/


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

5. Submit Pull Request

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


# Open PR on GitHub
# Link any related issues
# Describe your changes

Code Contributions

Code Style

We use:

  • Black for code formatting
  • isort for import sorting
  • flake8 for linting
  • mypy for type checking
# Format code
black src/ tests/


# Sort imports
isort src/ tests/


# Check linting
flake8 src/ tests/


# Type checking
mypy src/

Commit Messages

Follow Conventional Commits:

feat: add parallel agent execution
fix: resolve memory leak in agent pools
docs: update topology documentation
test: add tests for branch executor
refactor: simplify validation logic
perf: optimize message passing

Pull Request Guidelines

DO

  • Keep PRs focused on a single feature/fix
  • Include tests for new functionality
  • Update documentation
  • Add type hints
  • Follow existing code patterns
  • Link related issues

DON'T

  • Mix unrelated changes
  • Break existing tests
  • Introduce unnecessary dependencies
  • Change code style arbitrarily
  • Submit incomplete work

Testing

Test Structure

tests/
├── unit/           # Unit tests
├── integration/    # Integration tests
├── e2e/           # End-to-end tests
└── fixtures/      # Test fixtures

Writing Tests

import pytest
from marsys.agents import Agent


@pytest.mark.asyncio
async def test_agent_creation():
    """Test agent can be created with config."""
    agent = Agent(
        model_config=test_config,
        name="TestAgent",
        goal="Handle test tasks",
        instruction="Return deterministic outputs for tests."
    )


    assert agent.name == "TestAgent"
    assert agent.model is not None


@pytest.mark.asyncio
async def test_agent_execution():
    """Test agent can execute tasks."""
    agent = create_test_agent()
    result = await agent.run("Test task")


    assert result.success
    assert result.response is not None

Running Tests

# Run all tests
pytest


# Run with coverage
pytest --cov=src --cov-report=html


# Run specific test file
pytest tests/unit/test_agent.py


# Run with markers
pytest -m "not slow"

Architecture

Key Principles

  1. Pure Functions: Agents use pure _run() methods
  2. Centralized Validation: Single validation processor
  3. Dynamic Branching: Runtime parallel execution
  4. Topology-Driven: Graph-based routing

Adding New Features

  1. Identify Component: Where does it belong?
  2. Design API: Keep it consistent
  3. Implement: Follow existing patterns
  4. Test: Comprehensive test coverage
  5. Document: Update relevant docs

Release Process

Version Numbering

We follow Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes

Community

Code of Conduct

We follow the Contributor Covenant Code of Conduct. Be respectful, constructive, inclusive, and professional.

Getting Help

Current Priorities

High Priority

  • Performance optimization
  • Browser agent stability
  • Documentation improvements
  • Test coverage expansion

Feature Requests

  • Streaming responses
  • Distributed execution
  • Advanced learning agents
  • Custom storage backends

License

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

Thank You!

Every contribution makes MARSYS better. Whether it's fixing a typo, adding a feature, or helping others - we appreciate your effort!

First Time?

If this is your first open-source contribution, check out First Contributions for a gentle introduction.