pygeai-orchestration 0.1.0b2__tar.gz

pygeai_orchestration-0.1.0b2/BUILD.md

@@ -0,0 +1,318 @@
+# 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)

pygeai_orchestration-0.1.0b2/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to PyGEAI-Orchestration will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure and configuration
+- Core base classes for agents, orchestrators, and patterns
+- CLI framework with `geai-orch` command
+- Reflection pattern for iterative improvement
+- Tool Use pattern for function calling
+- ReAct pattern for reasoning and acting
+- Planning pattern for multi-step execution
+- Multi-Agent pattern for collaborative workflows
+- Comprehensive test suite with unit and integration tests
+- Documentation and examples for all patterns
+- GitHub Actions CI/CD workflows
+
+## [0.1.0b1] - 2026-02-05
+
+### Added
+- Initial beta release of PyGEAI-Orchestration
+- Foundation for agentic AI orchestration patterns
+- Integration with PyGEAI SDK
+- Basic project structure and tooling

pygeai_orchestration-0.1.0b2/CONTRIBUTING.md

@@ -0,0 +1,262 @@
+# 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!

pygeai_orchestration-0.1.0b2/LICENSE

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright © 2026 Globant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pygeai_orchestration-0.1.0b2/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include BUILD.md
+include CHANGELOG.md
+include requirements.txt
+include pyproject.toml
+recursive-include pygeai_orchestration *.py
+recursive-include docs *.md *.rst
+recursive-include snippets *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]