# Contributing to PyGEAI-Orchestration

Thank you for contributing to **PyGEAI-Orchestration**, the agentic AI orchestration framework for [Globant Enterprise AI](https://wiki.genexus.com/enterprise-ai/wiki?8,Table+of+contents%3AEnterprise+AI). This document outlines the guidelines for contributing to the project. All contributors are expected to follow these guidelines to ensure a consistent and high-quality codebase.

## Project Overview

PyGEAI-Orchestration provides orchestration patterns for building agentic AI systems on top of PyGEAI and Globant Enterprise AI. The project uses Python (>=3.10), adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), and maintains a [Changelog](https://keepachangelog.com/en/1.1.0/).

## How to Contribute

### 1. Fork and Clone (or Request Access)

If the repository allows forking:
```bash
git clone https://github.com/<your-username>/pygeai-orchestration.git
cd pygeai-orchestration
```

If not, contact the maintainers at [geai-sdk@globant.com](mailto:geai-sdk@globant.com) to request contributor access.

### 2. Set Up Development Environment

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

# Install dependencies
pip install -r requirements.txt

# Install in editable mode
pip install -e .
```

### 3. Create a Branch

Create a branch for your changes:
```bash
git checkout -b feature/your-feature-name
```

Use descriptive branch names:
- `feature/add-reflection-pattern`
- `bugfix/fix-agent-coordination`
- `docs/update-planning-guide`

### 4. Make Changes

Implement your changes following these guidelines:

#### Code Style
- Adhere to [PEP 8](https://www.python.org/dev/peps/pep-0008/)
- Use type hints for all function parameters and return values
- Maximum line length: 120 characters
- Use meaningful variable and function names

#### Docstrings
All public classes, methods, and functions must include docstrings:

```python
def orchestrate_agents(
    session: Session,
    agents: list[Agent],
    task: str,
    max_iterations: int = 10
) -> OrchestrationResult:
    """
    Orchestrates multiple agents to collaboratively solve a task.

    This method coordinates agent interactions, manages communication flow,
    and aggregates results from multiple agents working on the same task.

    :param session: Session - Active PyGEAI session for API access.
    :param agents: list[Agent] - List of agents to coordinate.
    :param task: str - The task description to be solved.
    :param max_iterations: int - Maximum number of coordination cycles. Defaults to 10.
    :return: OrchestrationResult - Contains final output and execution metadata.
    :raises ValueError: If agents list is empty or session is invalid.
    :raises OrchestrationError: If coordination fails after max_iterations.
    """
```

#### Testing
- Write unit tests for all new features
- Tests must be in the appropriate `tests/` subdirectory
- Use `unittest` framework
- Aim for >80% code coverage

Test format:
```python
class TestReflectionPattern(TestCase):
    """
    python -m unittest pygeai_orchestration.tests.patterns.test_reflection.TestReflectionPattern
    """
    
    def test_basic_reflection(self):
        # Test implementation
        pass
```

#### Documentation
New features must include:
- Updates to relevant documentation in `docs/`
- Pattern examples in `snippets/`
- Docstrings for all public APIs
- Updates to `README.md` if needed

#### Changelog
Update `CHANGELOG.md` under the `[Unreleased]` section:

```markdown
## [Unreleased]

### Added
- Reflection pattern with iterative improvement strategies
- Multi-agent coordination with consensus mechanisms

### Fixed
- Bug in tool registry parameter validation

### Changed
- Improved planning algorithm for better step decomposition
```

### 5. Test Your Changes

Run the test suite:
```bash
# Run all tests
python testing.py

# Run specific test
python -m unittest pygeai_orchestration.tests.patterns.test_reflection -v

# Check coverage
python testing.py --coverage
```

Verify code style:
```bash
# Using flake8
flake8 pygeai_orchestration --max-line-length=120

# Using ruff (if available)
ruff check pygeai_orchestration
```

### 6. Commit Changes

Use conventional commit prefixes:

| Prefix      | Purpose                                                 |
|-------------|---------------------------------------------------------|
| `feat:`     | New features (patterns, orchestrators, etc.)           |
| `fix:`      | Bug fixes                                               |
| `refactor:` | Code restructuring without behavior changes             |
| `docs:`     | Documentation updates                                   |
| `test:`     | Test additions or modifications                         |
| `build:`    | Build scripts, CI/CD, packaging                         |
| `perf:`     | Performance improvements                                |

Examples:
```bash
git commit -m "feat: add reflection pattern with self-critique"
git commit -m "fix: resolve agent coordination deadlock"
git commit -m "docs: update multi-agent pattern examples"
```

### 7. Push and Create Pull Request

```bash
git push origin feature/your-feature-name
```

Create a pull request with:
- Clear title describing the change
- Detailed description of what was changed and why
- References to related issues
- Screenshots/examples if applicable

## Development Guidelines

### Architecture Principles

1. **No Code Duplication**: Always import from PyGEAI rather than duplicating code
2. **Pattern Isolation**: Each pattern should be self-contained in its module
3. **Composability**: Patterns should be composable where it makes sense
4. **Extensibility**: Design for easy addition of new patterns

### Dependency Management

- Core dependency: `pygeai >= 0.7.0`
- Import from PyGEAI for all reusable components:
  ```python
  from pygeai.cli.commands import Command, Option, ArgumentsEnum
  from pygeai.cli.parsers import CommandParser
  from pygeai.core.base.session import get_session
  ```

### Adding New Patterns

When adding a new orchestration pattern:

1. Create pattern directory: `pygeai_orchestration/patterns/your_pattern/`
2. Implement core components:
   - `agent.py` - Pattern-specific agent class
   - `orchestrator.py` - Orchestration logic
   - Additional modules as needed
3. Add CLI command in `pygeai_orchestration/cli/commands/`
4. Write tests in `pygeai_orchestration/tests/patterns/`
5. Add examples in `snippets/your_pattern/`
6. Document in `docs/patterns/your-pattern.md`

### Testing Requirements

- Unit tests for all pattern components
- Integration tests for end-to-end workflows
- CLI command tests
- Mock PyGEAI sessions for unit tests
- Real integration tests (marked appropriately)

### Documentation Standards

- All public APIs must have complete docstrings
- Pattern documentation must include:
  - Conceptual overview
  - Use cases
  - Code examples
  - API reference
  - Best practices

## Code Review Process

1. All changes require at least one review
2. CI/CD checks must pass
3. Code coverage must not decrease
4. Documentation must be updated
5. Changelog must be updated

## Release Process

Releases are managed by maintainers:

1. Version bump in `pyproject.toml`
2. Update `CHANGELOG.md`
3. Create release tag
4. Publish to PyPI

## Getting Help

-  Email: [geai-sdk@globant.com](mailto:geai-sdk@globant.com)
-  Issues: [GitHub Issues](https://github.com/genexus-books/pygeai-orchestration/issues)
-  Discussions: [GitHub Discussions](https://github.com/genexus-books/pygeai-orchestration/discussions)

## Code of Conduct

- Be respectful and inclusive
- Provide constructive feedback
- Focus on what is best for the community
- Show empathy towards other community members

Thank you for contributing to PyGEAI-Orchestration!
