pygeai-orchestration 0.1.0b2__py3-none-any.whl

pygeai_orchestration/cli/interactive.py

@@ -0,0 +1,265 @@
+"""Interactive CLI utilities."""
+
+from typing import Any, Callable, Dict, List, Optional
+
+from pygeai_orchestration.cli.formatters import Color, OutputFormatter, Symbol
+
+
+class InteractivePrompt:
+    """Interactive prompt utilities."""
+
+    def __init__(self, formatter: Optional[OutputFormatter] = None):
+        """Initialize interactive prompt.
+
+        Args:
+            formatter: Output formatter
+        """
+        self.formatter = formatter or OutputFormatter()
+
+    def confirm(self, message: str, default: bool = True) -> bool:
+        """Ask yes/no confirmation.
+
+        Args:
+            message: Confirmation message
+            default: Default value
+
+        Returns:
+            User confirmation
+        """
+        default_str = "Y/n" if default else "y/N"
+        prompt = f"{message} [{default_str}]: "
+
+        while True:
+            response = input(prompt).strip().lower()
+
+            if not response:
+                return default
+
+            if response in ("y", "yes"):
+                return True
+            elif response in ("n", "no"):
+                return False
+            else:
+                print(self.formatter.error("Please answer yes or no"))
+
+    def select(
+        self,
+        message: str,
+        choices: List[str],
+        default: Optional[int] = None
+    ) -> int:
+        """Select from list of choices.
+
+        Args:
+            message: Selection message
+            choices: List of choices
+            default: Default choice index
+
+        Returns:
+            Selected index
+        """
+        print(f"\n{self.formatter.heading(message, level=2)}\n")
+
+        for i, choice in enumerate(choices, 1):
+            bullet = self.formatter.colorize(Symbol.ARROW.value, Color.BLUE)
+            default_mark = " (default)" if default == i - 1 else ""
+            print(f"{bullet} {i}. {choice}{default_mark}")
+
+        while True:
+            prompt = "\nEnter choice"
+            if default is not None:
+                prompt += f" [default: {default + 1}]"
+            prompt += ": "
+
+            response = input(prompt).strip()
+
+            if not response and default is not None:
+                return default
+
+            try:
+                index = int(response) - 1
+                if 0 <= index < len(choices):
+                    return index
+                else:
+                    print(self.formatter.error(f"Please enter a number between 1 and {len(choices)}"))
+            except ValueError:
+                print(self.formatter.error("Please enter a valid number"))
+
+    def multiselect(
+        self,
+        message: str,
+        choices: List[str],
+        defaults: Optional[List[int]] = None
+    ) -> List[int]:
+        """Select multiple choices.
+
+        Args:
+            message: Selection message
+            choices: List of choices
+            defaults: Default choice indices
+
+        Returns:
+            List of selected indices
+        """
+        defaults = defaults or []
+
+        print(f"\n{self.formatter.heading(message, level=2)}\n")
+        print(self.formatter.dim("Enter numbers separated by commas, or 'all' for all choices\n"))
+
+        for i, choice in enumerate(choices, 1):
+            bullet = self.formatter.colorize(Symbol.ARROW.value, Color.BLUE)
+            default_mark = " (selected)" if i - 1 in defaults else ""
+            print(f"{bullet} {i}. {choice}{default_mark}")
+
+        while True:
+            prompt = "\nEnter choices"
+            if defaults:
+                default_str = ",".join(str(i + 1) for i in defaults)
+                prompt += f" [default: {default_str}]"
+            prompt += ": "
+
+            response = input(prompt).strip().lower()
+
+            if not response and defaults:
+                return defaults
+
+            if response == "all":
+                return list(range(len(choices)))
+
+            try:
+                indices = [int(x.strip()) - 1 for x in response.split(",")]
+                if all(0 <= i < len(choices) for i in indices):
+                    return indices
+                else:
+                    print(self.formatter.error(f"All numbers must be between 1 and {len(choices)}"))
+            except ValueError:
+                print(self.formatter.error("Please enter valid numbers separated by commas"))
+
+    def text_input(
+        self,
+        message: str,
+        default: Optional[str] = None,
+        validator: Optional[Callable[[str], bool]] = None,
+        error_message: str = "Invalid input"
+    ) -> str:
+        """Get text input from user.
+
+        Args:
+            message: Input message
+            default: Default value
+            validator: Validation function
+            error_message: Error message for validation failure
+
+        Returns:
+            User input
+        """
+        prompt = message
+        if default:
+            prompt += f" [default: {default}]"
+        prompt += ": "
+
+        while True:
+            response = input(prompt).strip()
+
+            if not response and default:
+                return default
+
+            if not response:
+                print(self.formatter.error("Input cannot be empty"))
+                continue
+
+            if validator and not validator(response):
+                print(self.formatter.error(error_message))
+                continue
+
+            return response
+
+    def password_input(self, message: str) -> str:
+        """Get password input (hidden).
+
+        Args:
+            message: Input message
+
+        Returns:
+            User input
+        """
+        import getpass
+        return getpass.getpass(f"{message}: ")
+
+    def menu(
+        self,
+        title: str,
+        options: Dict[str, Callable[[], Any]],
+        show_exit: bool = True
+    ) -> None:
+        """Display interactive menu.
+
+        Args:
+            title: Menu title
+            options: Dictionary of option names to handlers
+            show_exit: Show exit option
+        """
+        choices = list(options.keys())
+        if show_exit:
+            choices.append("Exit")
+
+        while True:
+            try:
+                index = self.select(title, choices)
+
+                if show_exit and index == len(choices) - 1:
+                    print(self.formatter.info("Exiting..."))
+                    break
+
+                option_name = choices[index]
+                handler = options[option_name]
+
+                result = handler()
+
+                if result is False:
+                    break
+
+            except KeyboardInterrupt:
+                print("\n" + self.formatter.info("Interrupted by user"))
+                break
+            except Exception as e:
+                print(self.formatter.error(f"Error: {e}"))
+
+    def progress_steps(
+        self,
+        steps: List[str],
+        handlers: List[Callable[[], bool]]
+    ) -> bool:
+        """Execute steps with progress tracking.
+
+        Args:
+            steps: List of step descriptions
+            handlers: List of step handlers
+
+        Returns:
+            True if all steps completed successfully
+        """
+        if len(steps) != len(handlers):
+            raise ValueError("Number of steps and handlers must match")
+
+        print(f"\n{self.formatter.heading('Progress', level=2)}\n")
+
+        for i, (step, handler) in enumerate(zip(steps, handlers), 1):
+            step_msg = f"Step {i}/{len(steps)}: {step}"
+            print(self.formatter.info(step_msg))
+
+            try:
+                success = handler()
+
+                if success:
+                    print(self.formatter.success(f"Completed: {step}"))
+                else:
+                    print(self.formatter.error(f"Failed: {step}"))
+                    return False
+
+            except Exception as e:
+                print(self.formatter.error(f"Error in {step}: {e}"))
+                return False
+
+        print(f"\n{self.formatter.success('All steps completed successfully!')}\n")
+        return True

pygeai_orchestration/cli/texts/help.py

@@ -0,0 +1,169 @@
+"""
+Help text for the geai-orch CLI.
+"""
+
+CLI_USAGE = """
+geai-orch - Agentic AI Orchestration CLI for Globant Enterprise AI
+
+USAGE:
+    geai-orch [OPTIONS] <COMMAND> [ARGS]
+
+OPTIONS:
+    -a, --alias <ALIAS>         Use a specific credentials profile
+    --credentials <FILE>        Path to custom credentials file
+    -v, --verbose              Enable verbose logging
+    -h, --help                 Show help information
+    --version                  Show version information
+
+COMMANDS:
+    help                       Show help information
+    version                    Show version information
+    reflection                 Run reflection pattern
+    tool-use                   Execute tool use pattern
+    react                      Run ReAct (Reasoning + Acting) pattern
+    planning                   Execute planning pattern
+    multi-agent                Run multi-agent coordination pattern
+    run                        Quick run a pattern
+
+EXAMPLES:
+    # Show help
+    geai-orch help
+
+    # Run reflection pattern
+    geai-orch reflection --agent my-agent --iterations 3
+
+    # Execute ReAct pattern with custom task
+    geai-orch react --task "Solve complex problem" --max-steps 10
+
+    # Multi-agent collaboration
+    geai-orch multi-agent --config agents.yaml
+
+    # Use specific credentials profile
+    geai-orch --alias production reflection --agent my-agent
+
+For more information, visit: https://github.com/genexus-books/pygeai-orchestration
+"""
+
+VERSION_TEXT = """
+geai-orch version {version}
+PyGEAI-Orchestration - Agentic AI Orchestration Patterns
+
+Copyright © 2026 Globant
+Licensed under the MIT License
+"""
+
+HELP_REFLECTION = """
+reflection - Run reflection pattern for iterative improvement
+
+USAGE:
+    geai-orch reflection [OPTIONS]
+
+OPTIONS:
+    -a, --agent <ID>           Agent ID to use for reflection
+    -i, --iterations <N>       Number of reflection iterations (default: 3)
+    -t, --task <TEXT>          Task or text to improve
+    -o, --output <FILE>        Output file for results
+    -v, --verbose              Show detailed output
+
+DESCRIPTION:
+    The reflection pattern enables agents to self-critique and iteratively
+    improve their outputs through multiple reflection cycles.
+
+EXAMPLES:
+    geai-orch reflection --agent critic --task "Write a summary" --iterations 5
+    geai-orch reflection -a my-agent -t "Improve this code" -o result.txt
+"""
+
+HELP_TOOL_USE = """
+tool-use - Execute tool use pattern with function calling
+
+USAGE:
+    geai-orch tool-use [OPTIONS]
+
+OPTIONS:
+    -a, --agent <ID>           Agent ID to use
+    -t, --tools <FILE>         Tools configuration file (YAML/JSON)
+    --task <TEXT>              Task description
+    -o, --output <FILE>        Output file for results
+    -v, --verbose              Show detailed output
+
+DESCRIPTION:
+    The tool use pattern integrates function calling and external tool
+    execution into agent workflows.
+
+EXAMPLES:
+    geai-orch tool-use --agent worker --tools tools.yaml --task "Search for info"
+    geai-orch tool-use -a my-agent --task "Execute calculation"
+"""
+
+HELP_REACT = """
+react - Run ReAct (Reasoning + Acting) pattern
+
+USAGE:
+    geai-orch react [OPTIONS]
+
+OPTIONS:
+    -a, --agent <ID>           Agent ID to use
+    -t, --task <TEXT>          Task to solve
+    --max-steps <N>            Maximum reasoning-acting steps (default: 10)
+    -o, --output <FILE>        Output file for results
+    -v, --verbose              Show detailed reasoning trace
+
+DESCRIPTION:
+    The ReAct pattern implements a Reasoning + Acting loop for step-by-step
+    problem solving with explicit reasoning traces.
+
+EXAMPLES:
+    geai-orch react --agent reasoning-agent --task "Research topic" --max-steps 15
+    geai-orch react -a solver --task "Multi-step problem" -v
+"""
+
+HELP_PLANNING = """
+planning - Execute planning pattern for multi-step tasks
+
+USAGE:
+    geai-orch planning [OPTIONS]
+
+OPTIONS:
+    -a, --agent <ID>           Planner agent ID
+    -t, --task <TEXT>          Task to plan and execute
+    --plan-only                Only create plan, don't execute
+    -o, --output <FILE>        Output file for results
+    -v, --verbose              Show detailed execution trace
+
+DESCRIPTION:
+    The planning pattern creates and executes multi-step plans with
+    adaptive execution and progress tracking.
+
+EXAMPLES:
+    geai-orch planning --agent planner --task "Build web app"
+    geai-orch planning -a my-planner --task "Complex project" --plan-only
+"""
+
+HELP_MULTI_AGENT = """
+multi-agent - Run multi-agent coordination pattern
+
+USAGE:
+    geai-orch multi-agent [OPTIONS]
+
+OPTIONS:
+    -c, --config <FILE>        Agent configuration file (YAML/JSON)
+    -t, --task <TEXT>          Task for agents to collaborate on
+    --strategy <NAME>          Coordination strategy (default: sequential)
+    -o, --output <FILE>        Output file for results
+    -v, --verbose              Show agent communication details
+
+DESCRIPTION:
+    The multi-agent pattern coordinates multiple agents working
+    collaboratively on complex tasks with defined roles.
+
+STRATEGIES:
+    sequential    - Agents work one after another
+    parallel      - Agents work simultaneously
+    hierarchical  - Leader-worker coordination
+    consensus     - Agents reach consensus
+
+EXAMPLES:
+    geai-orch multi-agent --config agents.yaml --task "Research report"
+    geai-orch multi-agent -c team.yaml -t "Complex analysis" --strategy consensus
+"""

pygeai_orchestration/core/__init__.py

@@ -0,0 +1,130 @@
+from .base import (
+    BaseAgent,
+    AgentConfig,
+    BaseOrchestrator,
+    OrchestratorConfig,
+    BasePattern,
+    PatternConfig,
+    PatternResult,
+    PatternType,
+    BaseTool,
+    ToolConfig,
+    ToolResult,
+    ToolCategory,
+    GEAIAgent,
+    GEAIOrchestrator,
+)
+
+from .common import (
+    Message,
+    MessageRole,
+    Conversation,
+    Context,
+    ContextManager,
+    State,
+    StateStatus,
+    StateManager,
+    Memory,
+    MemoryEntry,
+    MemoryStore,
+)
+
+from .utils import (
+    OrchestrationLogger,
+    get_logger,
+    ConfigManager,
+    get_config,
+    ValidationResult,
+    validate_agent_config,
+    validate_pattern_config,
+    validate_tool_config,
+    validate_pydantic_model,
+    CacheEntry,
+    LRUCache,
+    PatternCache,
+    Metric,
+    MetricType,
+    MetricsCollector,
+    GlobalMetrics,
+    TimerContext,
+)
+
+from .exceptions import (
+    OrchestrationError,
+    PatternExecutionError,
+    PatternConfigurationError,
+    AgentError,
+    ToolExecutionError,
+    StateError,
+    ValidationError,
+)
+
+from .handlers import (
+    ErrorHandler,
+    RetryHandler,
+)
+
+from .composition import (
+    CompositionConfig,
+    CompositionMode,
+    PatternPipeline,
+    PatternComposer,
+)
+
+__all__ = [
+    "BaseAgent",
+    "AgentConfig",
+    "BaseOrchestrator",
+    "OrchestratorConfig",
+    "BasePattern",
+    "PatternConfig",
+    "PatternResult",
+    "PatternType",
+    "BaseTool",
+    "ToolConfig",
+    "ToolResult",
+    "ToolCategory",
+    "GEAIAgent",
+    "GEAIOrchestrator",
+    "Message",
+    "MessageRole",
+    "Conversation",
+    "Context",
+    "ContextManager",
+    "State",
+    "StateStatus",
+    "StateManager",
+    "Memory",
+    "MemoryEntry",
+    "MemoryStore",
+    "OrchestrationLogger",
+    "get_logger",
+    "ConfigManager",
+    "get_config",
+    "ValidationResult",
+    "validate_agent_config",
+    "validate_pattern_config",
+    "validate_tool_config",
+    "validate_pydantic_model",
+    "OrchestrationError",
+    "PatternExecutionError",
+    "PatternConfigurationError",
+    "AgentError",
+    "ToolExecutionError",
+    "StateError",
+    "ValidationError",
+    "ErrorHandler",
+    "RetryHandler",
+    "CacheEntry",
+    "LRUCache",
+    "PatternCache",
+    "Metric",
+    "MetricType",
+    "MetricsCollector",
+    "GlobalMetrics",
+    "TimerContext",
+    "CompositionConfig",
+    "CompositionMode",
+    "PatternPipeline",
+    "PatternComposer",
+]

pygeai_orchestration/core/base/__init__.py

@@ -0,0 +1,23 @@
+from .agent import BaseAgent, AgentConfig
+from .orchestrator import BaseOrchestrator, OrchestratorConfig
+from .pattern import BasePattern, PatternConfig, PatternResult, PatternType
+from .tool import BaseTool, ToolConfig, ToolResult, ToolCategory
+from .geai_agent import GEAIAgent
+from .geai_orchestrator import GEAIOrchestrator
+
+__all__ = [
+    "BaseAgent",
+    "AgentConfig",
+    "BaseOrchestrator",
+    "OrchestratorConfig",
+    "BasePattern",
+    "PatternConfig",
+    "PatternResult",
+    "PatternType",
+    "BaseTool",
+    "ToolConfig",
+    "ToolResult",
+    "ToolCategory",
+    "GEAIAgent",
+    "GEAIOrchestrator",
+]

pygeai_orchestration/core/base/agent.py

@@ -0,0 +1,121 @@
+"""
+Base agent definitions for orchestration agents.
+
+This module provides the foundation classes for all agent implementations,
+including configuration and the abstract base agent interface.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class AgentConfig(BaseModel):
+    """
+    Configuration model for agents.
+
+    This Pydantic model defines the configuration parameters for agent behavior,
+    including model selection, generation parameters, and optional tools.
+
+    :param name: str - Unique identifier for the agent.
+    :param description: Optional[str] - Human-readable description of agent purpose/role.
+    :param model: str - Model identifier (e.g., 'gpt-4', 'claude-3-opus').
+    :param temperature: float - Sampling temperature (0.0-2.0). Higher = more random.
+    :param max_tokens: Optional[int] - Maximum tokens to generate. None means model default.
+    :param system_prompt: Optional[str] - System-level instructions for the agent.
+    :param tools: List[str] - List of tool names available to this agent.
+    :param metadata: Dict[str, Any] - Custom metadata for agent-specific configuration.
+    """
+
+    name: str = Field(..., description="Agent name")
+    description: Optional[str] = Field(None, description="Agent description")
+    model: str = Field(..., description="Model identifier")
+    temperature: float = Field(0.7, ge=0.0, le=2.0)
+    max_tokens: Optional[int] = Field(None, ge=1)
+    system_prompt: Optional[str] = None
+    tools: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for all agent implementations.
+
+    This class defines the interface that all agent implementations must provide,
+    including task execution, text generation, and interaction history management.
+
+    Agents are the core execution units in orchestration patterns, responsible for:
+    - Generating text responses
+    - Executing tasks with context
+    - Managing conversation/interaction history
+
+    Subclasses must implement:
+    - execute(): Execute a task with optional context
+    - generate(): Generate text from a prompt
+    """
+
+    def __init__(self, config: AgentConfig):
+        """
+        Initialize the base agent with configuration.
+
+        :param config: AgentConfig - Configuration for this agent instance.
+        """
+        self.config = config
+        self.name = config.name
+        self.description = config.description
+        self._history: List[Dict[str, Any]] = []
+
+    @abstractmethod
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Execute a task with optional context.
+
+        This method provides high-level task execution with structured input/output.
+        Subclasses implement this to define task processing logic.
+
+        :param task: str - The task to execute.
+        :param context: Optional[Dict[str, Any]] - Additional context for execution.
+        :return: Dict[str, Any] - Execution results and metadata.
+        """
+        pass
+
+    @abstractmethod
+    async def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate text from a prompt.
+
+        This is the core text generation method used by patterns. Subclasses
+        implement this to interface with language models or other generation backends.
+
+        :param prompt: str - The prompt to generate from.
+        :param kwargs: Additional generation parameters (model-specific).
+        :return: str - Generated text response.
+        """
+        pass
+
+    def add_to_history(self, entry: Dict[str, Any]) -> None:
+        """
+        Add an entry to the agent's interaction history.
+
+        :param entry: Dict[str, Any] - History entry (e.g., prompt, response, metadata).
+        """
+        self._history.append(entry)
+
+    def get_history(self) -> List[Dict[str, Any]]:
+        """
+        Get a copy of the agent's interaction history.
+
+        :return: List[Dict[str, Any]] - Copy of history entries.
+        """
+        return self._history.copy()
+
+    def clear_history(self) -> None:
+        """
+        Clear the agent's interaction history.
+
+        Removes all history entries to start fresh.
+        """
+        self._history.clear()
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}(name='{self.name}')>"