# Build Guide for PyGEAI-Orchestration

This document outlines the build, test, and release process for PyGEAI-Orchestration.

## Development Setup

### Prerequisites

- Python >= 3.10
- pip
- virtualenv (recommended)
- Git

### Local Development Environment

1. **Clone the repository:**
   ```bash
   git clone https://github.com/genexus-books/pygeai-orchestration.git
   cd pygeai-orchestration
   ```

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

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Install in editable mode:**
   ```bash
   pip install -e .
   ```

5. **Verify installation:**
   ```bash
   geai-orch --help
   ```

## Building the Package

### Build from Source

```bash
# Clean previous builds
rm -rf build/ dist/ *.egg-info

# Build wheel and source distribution
python -m build

# Or using setuptools directly
python setup.py sdist bdist_wheel
```

### Build Output

Build artifacts are created in:
- `dist/` - Wheel (`.whl`) and source distribution (`.tar.gz`)
- `build/` - Temporary build files
- `*.egg-info/` - Package metadata

## Testing

### Run All Tests

```bash
python testing.py
```

### Run Unit Tests Only

```bash
python testing.py --unit
```

### Run Specific Test Module

```bash
python -m unittest pygeai_orchestration.tests.patterns.test_reflection -v
```

### Run Integration Tests

```bash
python testing.py --integration
```

### Coverage Report

```bash
# Run tests with coverage
python testing.py --coverage

# View HTML coverage report
open htmlcov/index.html  # On macOS
# or
xdg-open htmlcov/index.html  # On Linux
```

### Code Quality Checks

```bash
# PEP 8 compliance
flake8 pygeai_orchestration --max-line-length=120

# Type checking (if using mypy)
mypy pygeai_orchestration

# Security checks (if using bandit)
bandit -r pygeai_orchestration
```

## Documentation

### Build Sphinx Documentation

```bash
cd docs
make html
```

View documentation:
```bash
open _build/html/index.html
```

### Generate Markdown Documentation

```bash
cd docs
sphinx-build -b markdown source build/markdown
```

### Update Documentation

After making changes:
```bash
./scripts/update_docs.sh
```

## Version Management

### Bump Version

For regular releases:
```bash
python scripts/bump_version.py <major|minor|patch>
```

For beta releases:
```bash
python scripts/bump_beta_version.py
```

### Version Scheme

- **Stable releases**: `X.Y.Z` (e.g., `1.2.3`)
- **Beta releases**: `X.Y.ZbN` (e.g., `0.1.0b1`)

Following [Semantic Versioning](https://semver.org/):
- **MAJOR**: Breaking changes
- **MINOR**: New features, backward compatible
- **PATCH**: Bug fixes, backward compatible

## Release Process

### Pre-release Checklist

- [ ] All tests passing
- [ ] Coverage >= 80%
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Version bumped
- [ ] No security vulnerabilities

### Beta Release

```bash
# 1. Update version
python scripts/bump_beta_version.py

# 2. Update CHANGELOG.md
# Add release notes under appropriate version

# 3. Commit changes
git commit -m "release: version 0.1.0b1"

# 4. Create tag
git tag v0.1.0b1
git push origin v0.1.0b1

# 5. Build package
python -m build

# 6. Upload to TestPyPI (optional)
python -m twine upload --repository testpypi dist/*

# 7. Upload to PyPI
python -m twine upload dist/*
```

### Stable Release

```bash
# 1. Update version
python scripts/bump_version.py minor  # or major/patch

# 2. Update CHANGELOG.md
# Move [Unreleased] items to new version section

# 3. Commit changes
git commit -m "release: version 1.0.0"

# 4. Create tag
git tag v1.0.0
git push origin v1.0.0

# 5. Build and upload
python -m build
python -m twine upload dist/*
```

### GitHub Release

After pushing tag, create GitHub release:
1. Go to repository > Releases > Draft new release
2. Select the tag
3. Add release notes from CHANGELOG.md
4. Attach build artifacts (optional)
5. Publish release

## CI/CD

### GitHub Actions Workflows

Automated workflows in `.github/workflows/`:

- **test.yml**: Run tests on push/PR
- **coverage.yml**: Generate coverage reports
- **integration-tests.yml**: Run integration tests
- **docs.yml**: Build and deploy documentation
- **publish-beta.yml**: Publish beta to PyPI
- **publish.yml**: Publish stable to PyPI
- **codeql.yml**: Security scanning

### Triggering Workflows

- **Tests**: Automatic on push to any branch
- **Coverage**: Automatic on push to main/unstable
- **Beta Publish**: Manual or on beta tag push
- **Stable Publish**: Manual or on stable tag push

## Docker Build (Optional)

If Docker support is added:

```bash
# Build image
docker build -t pygeai-orchestration:latest .

# Run tests in container
docker run --rm pygeai-orchestration:latest python testing.py

# Run CLI in container
docker run --rm -it pygeai-orchestration:latest geai-orch --help
```

## Troubleshooting

### Common Issues

**Import errors after installation:**
```bash
pip uninstall pygeai-orchestration
pip install -e .
```

**Tests failing:**
```bash
# Clear test cache
rm -rf 
python testing.py --unit
```

**Build artifacts not clean:**
```bash
# Clean all build artifacts
rm -rf build/ dist/ *.egg-info __pycache__  htmlcov .coverage
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type f -name "*.pyc" -delete
```

## Development Scripts

Utility scripts in `scripts/`:

- `bump_version.py` - Version management
- `bump_beta_version.py` - Beta version bumping
- `check_coverage.sh` - Validate coverage thresholds
- `validate_test_coverage.py` - Test coverage validation
- `validate_test_integration.py` - Integration test validation
- `update_docs.sh` - Documentation update automation

## Resources

- [Python Packaging Guide](https://packaging.python.org/)
- [Setuptools Documentation](https://setuptools.pypa.io/)
- [PyPI Publishing](https://packaging.python.org/tutorials/packaging-projects/)
- [Semantic Versioning](https://semver.org/)

## Support

For build issues, contact:
- Email: geai-sdk@globant.com
- Issues: [GitHub Issues](https://github.com/genexus-books/pygeai-orchestration/issues)
