# PyGEAI-Orchestration - Agentic AI Orchestration Patterns

PyGEAI-Orchestration is a complementary package to [PyGEAI](https://pypi.org/project/pygeai/) that implements agentic AI orchestration patterns built on top of [Globant Enterprise AI](https://wiki.genexus.com/enterprise-ai/wiki?8,Table+of+contents%3AEnterprise+AI). It provides powerful orchestration capabilities similar to AutoGen and CrewAI, designed specifically for the Globant Enterprise AI platform.

> [!WARNING]
> This project is in Alpha stage and it's NOT suitable for production yet.
> While you can install the package and try it out, it's recommended to avoid using it in production until version 1.0.0
> is released

## Features

**Multiple Orchestration Patterns**
- **Reflection Pattern**: Self-critique and iterative improvement
- **Tool Use Pattern**: Function calling and tool integration
- **ReAct Pattern**: Reasoning + Acting loop for complex problem-solving
- **Planning Pattern**: Multi-step planning and execution
- **Multi-Agent Pattern**: Collaborative agent coordination

**Built on PyGEAI**
- Leverages PyGEAI's robust SDK capabilities
- Seamless integration with Globant Enterprise AI
- No code duplication - reuses PyGEAI infrastructure

**Easy to Use**
- Simple CLI tool: `geai-orch`
- Pythonic API for programmatic access
- Rich examples and documentation

## Installation

```bash
pip install pygeai-orchestration
```

**Requirements:**
- Python >= 3.10
- PyGEAI >= 0.7.0b9

## Quick Start

### CLI Usage

```bash
# Run a reflection pattern
geai-orch reflection --agent my-agent --iterations 3

# Execute a ReAct pattern
geai-orch react --agent reasoning-agent --task "Solve complex problem"

# Multi-agent collaboration
geai-orch multi-agent --config agents.yaml
```

### Python API

```python
import asyncio
from pygeai_orchestration import (
    GEAIAgent,
    AgentConfig,
    PatternConfig,
    PatternType,
    ReflectionPattern
)

async def main():
    # Create agent configuration
    agent_config = AgentConfig(
        name="my-agent",
        model="openai/gpt-4o-mini",
        temperature=0.7
    )
    agent = GEAIAgent(config=agent_config)
    
    # Create pattern configuration
    pattern_config = PatternConfig(
        name="reflection-example",
        pattern_type=PatternType.REFLECTION,
        max_iterations=3
    )
    
    # Create and execute pattern
    pattern = ReflectionPattern(agent=agent, config=pattern_config)
    result = await pattern.execute("Explain quantum computing in simple terms")
    
    print(f"Success: {result.success}")
    print(f"Iterations: {result.iterations}")
    print(f"Result: {result.result[:200]}...")  # First 200 chars

if __name__ == "__main__":
    asyncio.run(main())
```

## Configuration

PyGEAI-Orchestration uses the same configuration as PyGEAI. Set up your credentials using one of these methods:

**Environment Variables:**
```bash
export GEAI_API_KEY=<your-api-key>
export GEAI_API_BASE_URL=<base-url>
```

**Credentials File:**
Create `$USER_HOME/.geai/credentials`:
```ini
[default]
geai_api_key = <API_TOKEN>
geai_api_base_url = <GEAI_BASE_URL>
```

See [PyGEAI Configuration](https://docs.globant.ai/en/wiki?1149,Getting+started+with+PyGEAI) for more details.

## Orchestration Patterns

### 1. Reflection Pattern
Enables agents to self-critique and iteratively improve their outputs.

```python
from pygeai_orchestration import GEAIAgent, AgentConfig, PatternConfig, PatternType, ReflectionPattern

agent = GEAIAgent(config=AgentConfig(
    name="reflector",
    model="openai/gpt-4o-mini",
    temperature=0.7
))

pattern = ReflectionPattern(
    agent=agent,
    config=PatternConfig(
        name="reflection",
        pattern_type=PatternType.REFLECTION,
        max_iterations=3
    )
)

result = await pattern.execute("Explain quantum computing in simple terms")
```

**Use Cases:**
- Content quality improvement
- Code review and refinement
- Self-correcting responses

### 2. ReAct Pattern
Implements the Reasoning + Acting loop for step-by-step problem solving.

```python
from pygeai_orchestration import GEAIAgent, AgentConfig, PatternConfig, PatternType, ReActPattern

agent = GEAIAgent(config=AgentConfig(
    name="reasoner",
    model="openai/gpt-4o-mini",
    temperature=0.7
))

pattern = ReActPattern(
    agent=agent,
    config=PatternConfig(
        name="react",
        pattern_type=PatternType.REACT,
        max_iterations=5
    )
)

result = await pattern.execute("Research and summarize renewable energy benefits")
```

**Use Cases:**
- Complex problem solving
- Research tasks
- Multi-step workflows

### 3. Planning Pattern
Creates and executes multi-step plans with adaptive execution.

```python
from pygeai_orchestration import GEAIAgent, AgentConfig, PatternConfig, PatternType, PlanningPattern

agent = GEAIAgent(config=AgentConfig(
    name="planner",
    model="openai/gpt-4o-mini",
    temperature=0.5
))

pattern = PlanningPattern(
    agent=agent,
    config=PatternConfig(
        name="planning",
        pattern_type=PatternType.PLANNING,
        max_iterations=1
    )
)

result = await pattern.execute("Create a project plan for building a REST API")
```

**Use Cases:**
- Project planning
- Task decomposition
- Workflow automation

### 4. Tool Use Pattern
Integrates function calling and tool execution into agent workflows.

```python
from pygeai_orchestration import (
    GEAIAgent, AgentConfig, PatternConfig, PatternType,
    ToolUsePattern, BaseTool, ToolConfig, ToolResult, ToolCategory
)

class CalculatorTool(BaseTool):
    def __init__(self):
        super().__init__(ToolConfig(
            name="calculator",
            description="Performs calculations",
            category=ToolCategory.COMPUTATION,
            parameters_schema={"operation": "string", "values": "list"}
        ))
    
    def validate_parameters(self, parameters):
        return "operation" in parameters and "values" in parameters
    
    async def execute(self, operation, values, **kwargs):
        if operation == "average":
            result = sum(values) / len(values)
            return ToolResult(success=True, result=result)
        return ToolResult(success=False, error="Unknown operation")

agent = GEAIAgent(config=AgentConfig(name="calculator", model="openai/gpt-4o-mini"))
pattern = ToolUsePattern(
    agent=agent,
    config=PatternConfig(name="tools", pattern_type=PatternType.TOOL_USE),
    tools=[CalculatorTool()]
)

result = await pattern.execute("Calculate average of: 10, 20, 30")
```

**Use Cases:**
- API integration
- External data retrieval
- Action execution

### 5. Multi-Agent Pattern
Coordinates multiple agents working collaboratively on complex tasks.

```python
from pygeai_orchestration import (
    GEAIAgent, AgentConfig, PatternConfig, PatternType, MultiAgentPattern, AgentRole
)

# Create specialized agents
researcher = GEAIAgent(config=AgentConfig(
    name="researcher",
    model="openai/gpt-4o-mini",
    system_prompt="You are a research specialist."
))

writer = GEAIAgent(config=AgentConfig(
    name="writer",
    model="openai/gpt-4o-mini",
    system_prompt="You are a technical writer."
))

coordinator = GEAIAgent(config=AgentConfig(
    name="coordinator",
    model="openai/gpt-4o-mini",
    system_prompt="You coordinate tasks and synthesize results."
))

# Create agent roles
agent_roles = [
    AgentRole(name="researcher", agent=researcher, role_description="Researches topics"),
    AgentRole(name="writer", agent=writer, role_description="Writes reports")
]

# Create multi-agent pattern
pattern = MultiAgentPattern(
    agents=agent_roles,
    coordinator_agent=coordinator,
    config=PatternConfig(
        name="collaboration",
        pattern_type=PatternType.MULTI_AGENT
    )
)

result = await pattern.execute("Create a report on AI in healthcare")
```

**Use Cases:**
- Team collaboration simulation
- Complex task delegation
- Specialized agent workflows

## Documentation

- [Getting Started Guide](docs/getting-started.md)
- [Pattern Documentation](docs/patterns/)
- [API Reference](docs/api-reference/)
- [Code Snippets](snippets/)

## Development

### Setup Development Environment

```bash
cd pygeai-orchestration
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
```

### Running Tests

```bash
# Run all tests
python testing.py

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

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.

## Code Snippets

Check the [snippets/](snippets/) directory for working code examples:

### Reflection Pattern
- [reflection_explanation.py](snippets/reflection_explanation.py) - Iterative explanation improvement
- [reflection_code_review.py](snippets/reflection_code_review.py) - Code review with self-critique

### ReAct Pattern
- [react_research.py](snippets/react_research.py) - Structured research tasks
- [react_problem_solving.py](snippets/react_problem_solving.py) - Step-by-step problem solving

### Planning Pattern
- [planning_project.py](snippets/planning_project.py) - Project planning and breakdown
- [planning_analysis.py](snippets/planning_analysis.py) - Data analysis planning

### Tool Use Pattern
- [tool_use_calculator.py](snippets/tool_use_calculator.py) - Mathematical operations with tools
- [tool_use_data_processing.py](snippets/tool_use_data_processing.py) - Data validation and transformation

### Multi-Agent Pattern
- [multi_agent_collaboration.py](snippets/multi_agent_collaboration.py) - Collaborative multi-agent workflow

Run any snippet:
```bash
python snippets/reflection_explanation.py
python snippets/react_research.py
python snippets/planning_project.py
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.

## Terms and Conditions

By using this SDK, you agree to the [Globant Enterprise AI Terms of Use](https://www.globant.com/enterprise-ai/terms-of-use).

## Support

- [Documentation](docs/)
- Email: geai-sdk@globant.com

## Related Projects

- [PyGEAI](https://docs.globant.ai/en/wiki?1149,Getting+started+with+PyGEAI) - Core SDK for Globant Enterprise AI
- [AutoGen](https://github.com/microsoft/autogen) - Multi-agent framework by Microsoft
- [CrewAI](https://github.com/joaomdmoura/crewAI) - Framework for orchestrating AI agents

## Compatibility

This package is compatible with Globant Enterprise AI release from February 2026 and requires PyGEAI >= 0.7.0b9.

---

**Made by Globant**
