pygeai-orchestration 0.1.0b15

Agentic AI orchestration patterns built on Globant Enterprise AI

PyGEAI-Orchestration - Agentic AI Orchestration Patterns

PyGEAI-Orchestration is a complementary package to PyGEAI that implements agentic AI orchestration patterns built on top of Globant Enterprise AI. 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

pip install pygeai-orchestration

Requirements:

• Python >= 3.10
• PyGEAI >= 0.7.0b9

Quick Start

CLI Usage

# 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

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:

export GEAI_API_KEY=<your-api-key>
export GEAI_API_BASE_URL=<base-url>

Credentials File: Create $USER_HOME/.geai/credentials:

[default]
geai_api_key = <API_TOKEN>
geai_api_base_url = <GEAI_BASE_URL>

See PyGEAI Configuration for more details.

Orchestration Patterns

1. Reflection Pattern

Enables agents to self-critique and iteratively improve their outputs.

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.

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.

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.

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.

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

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 for all 41 tools with examples.

---

Documentation

• Getting Started Guide
• Pattern Documentation
• Tools Documentation ⭐ NEW
• API Reference
• Code Snippets

Development

Setup Development Environment

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

# 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 for detailed development guidelines.

Code Snippets

Check the snippets/ directory for working code examples:

Reflection Pattern

• reflection_explanation.py - Iterative explanation improvement
• reflection_code_review.py - Code review with self-critique

ReAct Pattern

• react_research.py - Structured research tasks
• react_problem_solving.py - Step-by-step problem solving

Planning Pattern

• planning_project.py - Project planning and breakdown
• planning_analysis.py - Data analysis planning

Tool Use Pattern

• tool_use_calculator.py - Mathematical operations with tools
• tool_use_data_processing.py - Data validation and transformation

Multi-Agent Pattern

• multi_agent_collaboration.py - Collaborative multi-agent workflow

Custom Patterns

• debate_pattern.py - Adversarial debate with pro/con arguments
• chain_of_thought_pattern.py - Explicit step-by-step reasoning
• iterative_refinement_pattern.py - Quality-based iterative improvement
• consensus_pattern.py - Multi-perspective consensus building

See snippets/custom/README.md for guide on creating your own custom patterns.

Run any snippet:

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

# 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

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

# ~/.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:

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:

export GEAI_ORCH_PLUGINS_DIR=/path/to/my/plugins

Documentation

See docs/source/plugins.rst for comprehensive plugin development guide.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see LICENSE for details.

Terms and Conditions

By using this SDK, you agree to the Globant Enterprise AI Terms of Use.

Support

• Documentation
• Email: [e-mail]

Related Projects

• PyGEAI - Core SDK for Globant Enterprise AI
• AutoGen - Multi-agent framework by Microsoft
• 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