Contributing

# 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

# 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

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

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

# 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"

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

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

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Check linting
flake8 src/ tests/

# Type checking
mypy src/

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

docs/
├── getting-started/    # Beginner guides
├── concepts/          # Core concepts
├── tutorials/         # Step-by-step tutorials
├── api/              # API reference
├── use-cases/        # Real-world examples
└── contributing/     # This section

# Feature Name

Brief description of what this feature does.

## Overview

Explain the purpose and use cases.

## Example

```python
# Complete, working example
from marsys import Feature

feature = Feature()
result = feature.do_something()
```

## API Reference

Document all public methods and parameters.

## Best Practices

Tips for effective usage.

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

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

# 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"