# 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

```bash
# 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

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

### 3. Set Up Development Environment

```bash
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](https://github.com/psf/black) for formatting
- Follow [PEP 8](https://pep8.org/) guidelines
- Type hints are encouraged

```bash
# 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

```bash
# Run tests
pytest

# With coverage
pytest --cov=backend
```

### Documentation

- Update docstrings for functions/classes
- Add/update documentation in [docs/](docs/) folder
- Update README if appropriate

```python
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
```

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

## Pull Request Process

1. **Update your branch**
   ```bash
   git fetch upstream
   git rebase upstream/main
   ```

2. **Push to your fork**
   ```bash
   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

```bash
docker-compose up --build
```

### Testing Agent Logic

```python
# 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

```python
# 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

```bash
# Clear cache
pytest --cache-clear

# Verbose output
pytest -vv

# Stop on first failure
pytest -x
```

### Import Errors

```bash
# Reinstall in development mode
pip install -e .

# Rebuild cache
python -m py_compile backend/
```

### Environment Issues

```bash
# 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! 🎉