Quick Start Guide
=================

This guide will help you get started with PyGEAI Orchestration in minutes.

Installation
------------

Install from PyPI::

    pip install pygeai-orchestration

Prerequisites
-------------

* Python 3.10 or higher
* PyGEAI SDK >= 0.7.0b9 (installed automatically)
* Valid GEAI API credentials

Configuration
-------------

Before using PyGEAI Orchestration, configure your Globant Enterprise AI credentials.

**Option 1: Credentials File (Recommended)**

Create ``~/.geai/credentials``::

    [default]
    geai_api_key = YOUR_API_KEY
    geai_api_base_url = YOUR_BASE_URL

**Option 2: Environment Variables**

.. code-block:: bash

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

See `PyGEAI Configuration <https://docs.globant.ai/en/wiki?1149,Getting+started+with+PyGEAI>`_ for more details.

Basic Concepts
--------------

PyGEAI Orchestration is built around three core concepts:

1. **Agents**: AI agents that can execute tasks using PyGEAI
2. **Patterns**: Orchestration patterns that coordinate agent behavior
3. **Tools**: External capabilities that agents can use

Quick Example
-------------

Here's a simple example using the Reflection pattern:

.. code-block:: 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}")

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

Using Orchestration Patterns
-----------------------------

Reflection Pattern
~~~~~~~~~~~~~~~~~~

Best for iterative refinement and quality improvement:

.. code-block:: python

    from pygeai_orchestration import (
        ReflectionPattern, PatternConfig, PatternType
    )

    pattern_config = PatternConfig(
        name="reflection",
        pattern_type=PatternType.REFLECTION,
        max_iterations=3
    )
    
    pattern = ReflectionPattern(agent=agent, config=pattern_config)
    result = await pattern.execute("Your task here")
    
    print(f"Success: {result.success}")
    print(f"Iterations: {result.iterations}")
    print(f"Result: {result.result}")

ReAct Pattern
~~~~~~~~~~~~~

Best for multi-step reasoning and research:

.. code-block:: python

    from pygeai_orchestration import (
        ReActPattern, PatternConfig, PatternType
    )

    pattern_config = PatternConfig(
        name="react",
        pattern_type=PatternType.REACT,
        max_iterations=5
    )
    
    pattern = ReActPattern(agent=agent, config=pattern_config)
    result = await pattern.execute("Research and analyze renewable energy")

Planning Pattern
~~~~~~~~~~~~~~~~

Best for task decomposition and project planning:

.. code-block:: python

    from pygeai_orchestration import (
        PlanningPattern, PatternConfig, PatternType
    )

    pattern_config = PatternConfig(
        name="planning",
        pattern_type=PatternType.PLANNING,
        max_iterations=1
    )
    
    pattern = PlanningPattern(agent=agent, config=pattern_config)
    result = await pattern.execute("Create a project plan for building a REST API")

Tool Use Pattern
~~~~~~~~~~~~~~~~

Best for tasks requiring external tools:

.. code-block:: python

    from pygeai_orchestration import (
        ToolUsePattern, BaseTool, ToolConfig, ToolResult,
        ToolCategory, PatternConfig, PatternType
    )

    class CalculatorTool(BaseTool):
        def __init__(self):
            super().__init__(ToolConfig(
                name="calculator",
                description="Performs mathematical calculations",
                category=ToolCategory.COMPUTATION,
                parameters_schema={
                    "operation": "string (add, average, etc.)",
                    "values": "list of numbers"
                }
            ))
        
        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)
            elif operation == "add":
                result = sum(values)
                return ToolResult(success=True, result=result)
            return ToolResult(success=False, error="Unknown operation")

    # Use the pattern
    pattern_config = PatternConfig(
        name="tools",
        pattern_type=PatternType.TOOL_USE,
        max_iterations=3
    )
    
    pattern = ToolUsePattern(
        agent=agent,
        config=pattern_config,
        tools=[CalculatorTool()]
    )
    
    result = await pattern.execute("Calculate the average of 10, 20, 30")

Multi-Agent Pattern
~~~~~~~~~~~~~~~~~~~

Best for collaborative workflows:

.. code-block:: python

    from pygeai_orchestration import (
        MultiAgentPattern, GEAIAgent, AgentConfig,
        PatternConfig, PatternType, 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 and gathers information"
        ),
        AgentRole(
            name="writer",
            agent=writer,
            role_description="Writes reports and documentation"
        )
    ]

    # Create pattern
    pattern_config = PatternConfig(
        name="collaboration",
        pattern_type=PatternType.MULTI_AGENT
    )
    
    pattern = MultiAgentPattern(
        agents=agent_roles,
        coordinator_agent=coordinator,
        config=pattern_config
    )
    
    result = await pattern.execute("Create a report on AI in healthcare")

Working Examples
----------------

Complete working examples are available in the ``snippets/`` directory:

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

Run any snippet::

    python snippets/reflection_explanation.py

Troubleshooting
---------------

Import Errors
~~~~~~~~~~~~~

Make sure you're using absolute imports::

    from pygeai_orchestration import GEAIAgent  # ✓ Correct
    from pygeai_orchestration.core.base import GEAIAgent  # ✓ Also correct

Model Names
~~~~~~~~~~~

Always include the provider prefix::

    model="openai/gpt-4o-mini"  # ✓ Correct
    model="gpt-4"  # ✗ Wrong - missing provider

Credentials Not Found
~~~~~~~~~~~~~~~~~~~~~

Ensure credentials are in ``~/.geai/credentials`` or environment variables are set.

Pattern Configuration
~~~~~~~~~~~~~~~~~~~~~

All patterns require a ``PatternConfig``:

.. code-block:: python

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

Next Steps
----------

* Read the :doc:`patterns` guide for detailed pattern documentation
* Explore :doc:`examples` for real-world use cases
* Check the :doc:`api/core` for complete API reference
* Learn about :doc:`contributing` to the project
