pygeai-orchestration 0.1.0b15
Agentic AI orchestration patterns built on Globant Enterprise AI
Requires Python: >=3.10
Keywords: geai, pygeai, orchestration, agents, ai, multi-agent, autogen, crewai

# 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://docs.globant.ai/en/wiki?15,Globant+Enterprise+AI+Overview). It provides powerful orchestration capabilities similar to AutoGen and CrewAI, designed specifically for the Globant Enterprise AI platform.

PyGEAI-Orchestration is a pattern-driven agent orchestration framework for enterprise environments, providing explicit, testable, and extensible agent workflows on top of Globant Enterprise AI — comparable to AutoGen and CrewAI, but designed for governance, reuse, and long-term maintainability.


> [!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 xp reflection -m openai/gpt-4o-mini -t "Improve this text" -i 3

# Execute a ReAct pattern
geai-orch pattern react -m openai/gpt-4o-mini -t "Solve complex problem"

# Multi-agent collaboration
geai-orch execute-pattern multi-agent -m openai/gpt-4o-mini -t "Task" -c agents.json
```

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

## Built-in Tools

PyGEAI-Orchestration includes **41 built-in tools** across 5 categories:

### Tool Categories

- 🔍 **SEARCH** (2 tools): Web search, Wikipedia
- 🧮 **COMPUTATION** (4 tools): Math, statistics, embeddings, reranking
- 📊 **DATA_ACCESS** (11 tools): File I/O, CSV, JSON, SQL, PDF, DOCX, Markdown
- 💬 **COMMUNICATION** (3 tools): Email, webhooks, Slack
- 🛠️ **CUSTOM** (21 tools): Text processing, validation, image tools, utilities

### Quick Example

```python
from pygeai_orchestration.tools.builtin.math_tools import MathCalculatorTool

tool = MathCalculatorTool()
result = await tool.execute(operation='add', values=[10, 20, 30])
print(result.result)  # 60
```

### GEAI-Powered Tools

- **OmniParserTool**: OCR and document parsing
- **EmbeddingsGeneratorTool**: Semantic search embeddings
- **RerankTool**: Relevance-based reranking
- **FileUploadTool / FileDownloadTool**: Cloud storage integration

**📚 Complete Documentation:** See [tools/README.md](pygeai_orchestration/tools/README.md) for all 41 tools with examples.

---

## Documentation

- [Getting Started Guide](docs/getting-started.md)
- [Pattern Documentation](docs/patterns/)
- [Tools Documentation](pygeai_orchestration/tools/README.md) ⭐ NEW
- [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

### Custom Patterns
- [debate_pattern.py](snippets/custom/debate_pattern.py) - Adversarial debate with pro/con arguments
- [chain_of_thought_pattern.py](snippets/custom/chain_of_thought_pattern.py) - Explicit step-by-step reasoning
- [iterative_refinement_pattern.py](snippets/custom/iterative_refinement_pattern.py) - Quality-based iterative improvement
- [consensus_pattern.py](snippets/custom/consensus_pattern.py) - Multi-perspective consensus building

See [snippets/custom/README.md](snippets/custom/README.md) for guide on creating your own custom patterns.

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

## Plugin System

The `geai-orch` CLI supports a **plugin system** for custom patterns, allowing you to use your own patterns via the command line without modifying the core codebase.

### Quick Start

```bash
# 1. Create plugin directory
mkdir -p ~/.geai-orch/plugins/

# 2. Copy a custom pattern (or create your own)
cp snippets/custom/debate_pattern.py ~/.geai-orch/plugins/

# 3. Use it immediately via CLI as a subcommand!
geai-orch xp debate --task "Should we adopt microservices architecture?"
```

### Plugin Management

```bash
# List all discovered custom patterns
geai-orch plugins list

# Get detailed info about a specific pattern
geai-orch plugins info --name debate
```

### Creating a Plugin

Create a Python file in `~/.geai-orch/plugins/` that inherits from `BasePattern`:

```python
# ~/.geai-orch/plugins/my_pattern.py
from typing import Any, Dict, Optional
from pygeai_orchestration.core.base import BasePattern, PatternConfig, PatternResult

class MyCustomPattern(BasePattern):
    """Brief description of what this pattern does."""
    
    def __init__(self, agent, config: PatternConfig):
        super().__init__(config)
        self.agent = agent
    
    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> PatternResult:
        self.reset()
        try:
            # Your pattern logic here
            result = await self.agent.generate(task)
            return PatternResult(success=True, result=result, iterations=self.current_iteration)
        except Exception as e:
            return PatternResult(success=False, error=str(e))
    
    async def step(self, state: Dict[str, Any]) -> Dict[str, Any]:
        # Implement step logic if needed
        return state
```

The CLI will automatically discover your pattern and make it available as a subcommand:
```bash
geai-orch xp my-custom --task "your task"
geai-orch pattern my-custom --task "your task" --model openai/gpt-4o
geai-orch execute-pattern my-custom --task "your task" --max-iterations 10
```

### Pattern Naming

Class names are automatically converted to CLI-friendly names:
- `MyCustomPattern` → `my-custom`
- `ChainOfThoughtPattern` → `chain-of-thought`
- `DebatePattern` → `debate`

### Plugin Directory

Default: `~/.geai-orch/plugins/`

Override with environment variable:
```bash
export GEAI_ORCH_PLUGINS_DIR=/path/to/my/plugins
```

### Documentation

See [docs/source/plugins.rst](docs/source/plugins.rst) for comprehensive plugin development guide.

## 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**