pygeai-orchestration 0.1.0b2__py3-none-any.whl

pygeai_orchestration/core/base/geai_agent.py

@@ -0,0 +1,144 @@
+"""
+PyGEAI-based agent implementation.
+
+This module provides a concrete agent implementation using the PyGEAI SDK,
+enabling AI-powered task execution with GeneXus Enterprise AI.
+"""
+
+from typing import Any, Dict, Optional
+from .agent import BaseAgent, AgentConfig
+from ..utils import get_logger
+
+logger = get_logger()
+
+try:
+    from pygeai import Session
+
+    PYGEAI_AVAILABLE = True
+except ImportError:
+    PYGEAI_AVAILABLE = False
+    logger.warning("PyGEAI not available. GEAIAgent will have limited functionality.")
+
+
+class GEAIAgent(BaseAgent):
+    """
+    Agent implementation using PyGEAI SDK.
+
+    This agent leverages the PyGEAI SDK to execute tasks using GeneXus
+    Enterprise AI models, providing AI-powered reasoning and generation.
+
+    The agent:
+    - Integrates with PyGEAI Session and Agent resources
+    - Supports custom system prompts and model configuration
+    - Automatically manages agent resource creation
+    - Maintains execution history
+    """
+
+    def __init__(self, config: AgentConfig, session=None, alias: Optional[str] = None):
+        """
+        Initialize the GEAI agent with PyGEAI session.
+
+        :param config: AgentConfig - Agent configuration.
+        :param session: Optional PyGEAI Session - Existing session to use.
+        :param alias: Optional[str] - Session alias if creating new session.
+        :raises ImportError: If PyGEAI is not installed.
+        """
+        super().__init__(config)
+        if not PYGEAI_AVAILABLE:
+            raise ImportError("PyGEAI is required for GEAIAgent but is not installed")
+        self._session = session or Session(alias=alias)
+        self._agent_resource = None
+
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Execute a task using PyGEAI generation.
+
+        :param task: str - Task description or instruction.
+        :param context: Optional[Dict[str, Any]] - Execution context.
+        :return: Dict[str, Any] - Execution result with success status and output.
+        """
+        logger.debug(f"GEAIAgent '{self.name}' executing task")
+
+        try:
+            result = await self.generate(task, context=context)
+
+            execution_result = {
+                "success": True,
+                "result": result,
+                "agent": self.name,
+                "metadata": context or {},
+            }
+
+            self.add_to_history(execution_result)
+            return execution_result
+
+        except Exception as e:
+            logger.error(f"GEAIAgent execution failed: {str(e)}")
+            error_result = {"success": False, "result": None, "error": str(e), "agent": self.name}
+            self.add_to_history(error_result)
+            return error_result
+
+    async def generate(self, prompt: str, **kwargs) -> str:
+        """
+        Generate a response using PyGEAI chat completion.
+
+        :param prompt: str - Input prompt for generation.
+        :param kwargs: Additional generation parameters (messages, etc.).
+        :return: str - Generated text response.
+        :raises Exception: If generation fails.
+        """
+        try:
+            self._get_or_create_agent()
+
+            messages = kwargs.get("messages", [])
+            if not messages:
+                messages = [{"role": "user", "content": prompt}]
+
+            if self.config.system_prompt:
+                messages.insert(0, {"role": "system", "content": self.config.system_prompt})
+
+            chat = self._session.chats.create(
+                messages=messages,
+                model=self.config.model,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens,
+            )
+
+            response = chat.choices[0].message.content
+
+            self.add_to_history({"type": "generation", "prompt": prompt, "response": response})
+
+            return response
+
+        except Exception as e:
+            logger.error(f"Generation failed: {str(e)}")
+            raise
+
+    def _get_or_create_agent(self):
+        """
+        Get or create PyGEAI agent resource.
+
+        Lazily creates an agent resource in PyGEAI if not already created,
+        or reuses existing agent with matching name.
+
+        :return: PyGEAI Agent resource.
+        """
+        if self._agent_resource is None:
+            try:
+                agents = self._session.agents.list()
+                for agent in agents.data:
+                    if agent.name == self.name:
+                        self._agent_resource = agent
+                        break
+
+                if self._agent_resource is None:
+                    logger.debug(f"Creating new agent resource: {self.name}")
+                    self._agent_resource = self._session.agents.create(
+                        name=self.name,
+                        model=self.config.model,
+                        description=self.config.description or f"Orchestration agent: {self.name}",
+                    )
+            except Exception as e:
+                logger.warning(f"Could not create agent resource: {str(e)}")
+
+        return self._agent_resource

pygeai_orchestration/core/base/geai_orchestrator.py

@@ -0,0 +1,77 @@
+from typing import Any, Dict, List, Optional
+from .orchestrator import BaseOrchestrator, OrchestratorConfig
+from .pattern import PatternResult
+from ..utils import get_logger
+
+logger = get_logger()
+
+
+class GEAIOrchestrator(BaseOrchestrator):
+    def __init__(self, config: OrchestratorConfig):
+        super().__init__(config)
+        self._execution_history: List[Dict[str, Any]] = []
+
+    async def orchestrate(
+        self, task: str, pattern: str, context: Optional[Dict[str, Any]] = None
+    ) -> PatternResult:
+        logger.info(f"Orchestrating task with pattern '{pattern}': {task[:50]}...")
+
+        pattern_instance = self.get_pattern(pattern)
+        if pattern_instance is None:
+            error_msg = f"Pattern '{pattern}' not found. Available: {self.list_patterns()}"
+            logger.error(error_msg)
+            return PatternResult(success=False, result=None, iterations=0, error=error_msg)
+
+        try:
+            result = await pattern_instance.execute(task, context)
+
+            self._execution_history.append(
+                {
+                    "task": task,
+                    "pattern": pattern,
+                    "success": result.success,
+                    "iterations": result.iterations,
+                    "result": result.result,
+                }
+            )
+
+            logger.info(
+                f"Orchestration {'succeeded' if result.success else 'failed'} "
+                f"after {result.iterations} iterations"
+            )
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Orchestration error: {str(e)}")
+            return PatternResult(success=False, result=None, iterations=0, error=str(e))
+
+    async def coordinate_agents(self, agents: List[str], task: str) -> Dict[str, Any]:
+        logger.info(f"Coordinating {len(agents)} agents for task: {task[:50]}...")
+
+        results = {}
+
+        for agent_name in agents:
+            agent = self.get_agent(agent_name)
+            if agent is None:
+                logger.warning(f"Agent '{agent_name}' not found, skipping")
+                continue
+
+            try:
+                result = await agent.execute(task)
+                results[agent_name] = result
+            except Exception as e:
+                logger.error(f"Agent '{agent_name}' failed: {str(e)}")
+                results[agent_name] = {"success": False, "error": str(e)}
+
+        return {
+            "success": len(results) > 0,
+            "results": results,
+            "agents_executed": list(results.keys()),
+        }
+
+    def get_execution_history(self) -> List[Dict[str, Any]]:
+        return self._execution_history.copy()
+
+    def clear_history(self) -> None:
+        self._execution_history.clear()

pygeai_orchestration/core/base/orchestrator.py

@@ -0,0 +1,142 @@
+"""
+Orchestrator base classes for managing agents and patterns.
+
+This module provides the foundation for orchestrating multiple agents
+and patterns, including registration, coordination, and task delegation.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from .agent import BaseAgent
+from .pattern import BasePattern, PatternResult
+
+
+class OrchestratorConfig(BaseModel):
+    """
+    Configuration model for orchestrators.
+
+    This Pydantic model defines orchestrator behavior including
+    concurrency limits, timeouts, and retry policies.
+
+    :param name: str - Unique identifier for the orchestrator.
+    :param max_concurrent_tasks: int - Maximum number of tasks to run concurrently.
+    :param timeout: Optional[float] - Global timeout in seconds. None means no timeout.
+    :param retry_attempts: int - Number of retry attempts on task failure.
+    :param metadata: Dict[str, Any] - Custom metadata for orchestrator configuration.
+    """
+
+    name: str = Field(..., description="Orchestrator name")
+    max_concurrent_tasks: int = Field(5, ge=1, description="Max concurrent tasks")
+    timeout: Optional[float] = Field(None, ge=0.0, description="Global timeout in seconds")
+    retry_attempts: int = Field(3, ge=0, description="Number of retry attempts on failure")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class BaseOrchestrator(ABC):
+    """
+    Abstract base class for orchestrator implementations.
+
+    This class defines the interface for orchestrating multiple agents
+    and patterns, enabling complex multi-agent workflows and pattern chaining.
+
+    Orchestrators manage:
+    - Agent registration and retrieval
+    - Pattern registration and selection
+    - Task delegation and coordination
+    - Multi-agent collaboration
+
+    Subclasses must implement:
+    - orchestrate(): Execute a task using a specific pattern
+    - coordinate_agents(): Coordinate multiple agents on a task
+    """
+
+    def __init__(self, config: OrchestratorConfig):
+        """
+        Initialize the orchestrator with configuration.
+
+        :param config: OrchestratorConfig - Configuration for this orchestrator.
+        """
+        self.config = config
+        self.name = config.name
+        self._agents: Dict[str, BaseAgent] = {}
+        self._patterns: Dict[str, BasePattern] = {}
+
+    def register_agent(self, agent: BaseAgent) -> None:
+        """
+        Register an agent with this orchestrator.
+
+        :param agent: BaseAgent - Agent to register.
+        """
+        self._agents[agent.name] = agent
+
+    def register_pattern(self, pattern: BasePattern) -> None:
+        """
+        Register a pattern with this orchestrator.
+
+        :param pattern: BasePattern - Pattern to register.
+        """
+        self._patterns[pattern.name] = pattern
+
+    def get_agent(self, name: str) -> Optional[BaseAgent]:
+        """
+        Retrieve a registered agent by name.
+
+        :param name: str - Agent name.
+        :return: Optional[BaseAgent] - The agent if found, None otherwise.
+        """
+        return self._agents.get(name)
+
+    def get_pattern(self, name: str) -> Optional[BasePattern]:
+        """
+        Retrieve a registered pattern by name.
+
+        :param name: str - Pattern name.
+        :return: Optional[BasePattern] - The pattern if found, None otherwise.
+        """
+        return self._patterns.get(name)
+
+    def list_agents(self) -> List[str]:
+        """
+        List all registered agent names.
+
+        :return: List[str] - Agent names.
+        """
+        return list(self._agents.keys())
+
+    def list_patterns(self) -> List[str]:
+        """
+        List all registered pattern names.
+
+        :return: List[str] - Pattern names.
+        """
+        return list(self._patterns.keys())
+
+    @abstractmethod
+    async def orchestrate(
+        self, task: str, pattern: str, context: Optional[Dict[str, Any]] = None
+    ) -> PatternResult:
+        """
+        Execute a task using a specified pattern.
+
+        :param task: str - Task description or instruction.
+        :param pattern: str - Name of the pattern to use.
+        :param context: Optional[Dict[str, Any]] - Execution context.
+        :return: PatternResult - Execution result.
+        """
+        pass
+
+    @abstractmethod
+    async def coordinate_agents(self, agents: List[str], task: str) -> Dict[str, Any]:
+        """
+        Coordinate multiple agents to complete a task.
+
+        :param agents: List[str] - Names of agents to coordinate.
+        :param task: str - Task description or instruction.
+        :return: Dict[str, Any] - Coordination results.
+        """
+        pass
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}(name='{self.name}', agents={len(self._agents)}, patterns={len(self._patterns)})>"

pygeai_orchestration/core/base/pattern.py

@@ -0,0 +1,161 @@
+"""
+Base pattern definitions for orchestration patterns.
+
+This module provides the foundation classes for all orchestration patterns,
+including configuration, results, and the abstract base pattern interface.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+from enum import Enum
+
+
+class PatternType(str, Enum):
+    """
+    Enumeration of available orchestration pattern types.
+
+    Each pattern type represents a distinct approach to agentic AI orchestration:
+    - REFLECTION: Iterative self-critique and refinement
+    - TOOL_USE: External tool integration and execution
+    - REACT: Reasoning and acting with thought traces
+    - PLANNING: Task decomposition and sequential execution
+    - MULTI_AGENT: Collaborative multi-agent problem solving
+    """
+
+    REFLECTION = "reflection"
+    TOOL_USE = "tool_use"
+    REACT = "react"
+    PLANNING = "planning"
+    MULTI_AGENT = "multi_agent"
+
+
+class PatternConfig(BaseModel):
+    """
+    Configuration model for orchestration patterns.
+
+    This Pydantic model defines the configuration parameters that control
+    pattern execution behavior, including iteration limits, timeouts, and
+    custom metadata.
+
+    :param name: str - Unique identifier for the pattern instance.
+    :param pattern_type: PatternType - The type of orchestration pattern.
+    :param max_iterations: int - Maximum number of iterations allowed (minimum 1).
+    :param timeout: Optional[float] - Execution timeout in seconds. None means no timeout.
+    :param verbose: bool - Enable detailed logging output. Defaults to False.
+    :param metadata: Dict[str, Any] - Custom metadata for pattern-specific configuration.
+    """
+
+    name: str = Field(..., description="Pattern name")
+    pattern_type: PatternType = Field(..., description="Type of orchestration pattern")
+    max_iterations: int = Field(10, ge=1, description="Maximum iterations")
+    timeout: Optional[float] = Field(None, ge=0.0, description="Timeout in seconds")
+    verbose: bool = Field(False, description="Enable verbose output")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class PatternResult(BaseModel):
+    """
+    Result model for pattern execution outcomes.
+
+    This Pydantic model encapsulates the results of pattern execution,
+    including success status, output data, iteration count, errors, and
+    execution metadata.
+
+    :param success: bool - Whether the pattern execution succeeded.
+    :param result: Any - The final output or answer from pattern execution.
+    :param iterations: int - Number of iterations executed (minimum 0).
+    :param error: Optional[str] - Error message if execution failed. None on success.
+    :param metadata: Dict[str, Any] - Additional execution metadata (e.g., intermediate results, timing).
+    """
+
+    success: bool = Field(..., description="Whether pattern execution succeeded")
+    result: Any = Field(None, description="Pattern execution result")
+    iterations: int = Field(0, ge=0, description="Number of iterations executed")
+    error: Optional[str] = Field(None, description="Error message if failed")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class BasePattern(ABC):
+    """
+    Abstract base class for all orchestration patterns.
+
+    This class defines the interface that all orchestration patterns must implement,
+    including the core execute() and step() methods. It provides common functionality
+    for iteration tracking and state management.
+
+    Subclasses must implement:
+    - execute(): Main entry point for pattern execution
+    - step(): Single iteration/step logic
+
+    The base class handles iteration counting and provides lifecycle hooks for
+    pattern initialization and reset.
+    """
+
+    def __init__(self, config: PatternConfig):
+        """
+        Initialize the base pattern with configuration.
+
+        :param config: PatternConfig - Configuration for this pattern instance.
+        """
+        self.config = config
+        self.name = config.name
+        self.pattern_type = config.pattern_type
+        self._iteration_count = 0
+
+    @abstractmethod
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> PatternResult:
+        """
+        Execute the orchestration pattern on the given task.
+
+        This is the main entry point for pattern execution. Subclasses must
+        implement this method to define their specific orchestration logic.
+
+        :param task: str - The task or question to execute.
+        :param context: Optional[Dict[str, Any]] - Additional context for execution.
+        :return: PatternResult - Execution results including success status and output.
+        """
+        pass
+
+    @abstractmethod
+    async def step(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Execute a single iteration step of the pattern.
+
+        This method defines the logic for one iteration of the pattern's execution
+        loop. Subclasses implement this to define step-level behavior.
+
+        :param state: Dict[str, Any] - Current state including iteration count, history, etc.
+        :return: Dict[str, Any] - Step results and updated state information.
+        """
+        pass
+
+    def reset(self) -> None:
+        """
+        Reset the pattern state for a new execution.
+
+        Clears iteration count and any other stateful information to prepare
+        for a fresh pattern execution.
+        """
+        self._iteration_count = 0
+
+    def increment_iteration(self) -> int:
+        """
+        Increment the iteration counter and return the new count.
+
+        :return: int - The new iteration count after incrementing.
+        """
+        self._iteration_count += 1
+        return self._iteration_count
+
+    @property
+    def current_iteration(self) -> int:
+        """
+        Get the current iteration count.
+
+        :return: int - Current iteration number (0-indexed).
+        """
+        return self._iteration_count
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}(name='{self.name}', type='{self.pattern_type.value}')>"

pygeai_orchestration/core/base/tool.py

@@ -0,0 +1,149 @@
+"""
+Base tool definitions for orchestration tools.
+
+This module provides the foundation classes for all tool implementations,
+including configuration, results, and the abstract base tool interface.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+from enum import Enum
+
+
+class ToolCategory(str, Enum):
+    """
+    Enumeration of tool categories.
+
+    Categories help organize and classify tools by their primary function:
+    - SEARCH: Web search, knowledge retrieval
+    - COMPUTATION: Calculators, data processing, algorithms
+    - DATA_ACCESS: Database queries, file access, API calls
+    - COMMUNICATION: Email, messaging, notifications
+    - CUSTOM: User-defined or specialized tools
+    """
+
+    SEARCH = "search"
+    COMPUTATION = "computation"
+    DATA_ACCESS = "data_access"
+    COMMUNICATION = "communication"
+    CUSTOM = "custom"
+
+
+class ToolConfig(BaseModel):
+    """
+    Configuration model for tools.
+
+    This Pydantic model defines the configuration parameters for tool behavior,
+    including metadata, parameter schemas, and execution limits.
+
+    :param name: str - Unique identifier for the tool.
+    :param description: str - Human-readable description of tool functionality.
+    :param category: ToolCategory - Category classification for the tool.
+    :param parameters_schema: Dict[str, Any] - JSON schema for tool parameters.
+    :param timeout: Optional[float] - Execution timeout in seconds. None means no timeout.
+    :param metadata: Dict[str, Any] - Custom metadata for tool-specific configuration.
+    """
+
+    name: str = Field(..., description="Tool name")
+    description: str = Field(..., description="Tool description")
+    category: ToolCategory = Field(ToolCategory.CUSTOM, description="Tool category")
+    parameters_schema: Dict[str, Any] = Field(default_factory=dict)
+    timeout: Optional[float] = Field(None, ge=0.0, description="Tool execution timeout")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResult(BaseModel):
+    """
+    Result model for tool execution outcomes.
+
+    This Pydantic model encapsulates the results of tool execution,
+    including success status, output data, errors, and execution metrics.
+
+    :param success: bool - Whether the tool execution succeeded.
+    :param result: Any - The output data from tool execution.
+    :param error: Optional[str] - Error message if execution failed. None on success.
+    :param execution_time: Optional[float] - Time taken to execute in seconds.
+    :param metadata: Dict[str, Any] - Additional execution metadata.
+    """
+
+    success: bool = Field(..., description="Whether tool execution succeeded")
+    result: Any = Field(None, description="Tool execution result")
+    error: Optional[str] = Field(None, description="Error message if failed")
+    execution_time: Optional[float] = Field(None, description="Execution time in seconds")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class BaseTool(ABC):
+    """
+    Abstract base class for all tool implementations.
+
+    This class defines the interface that all tool implementations must provide,
+    including execution, parameter validation, and schema retrieval.
+
+    Tools extend agent capabilities by providing access to:
+    - External APIs and services
+    - Computational operations
+    - Data retrieval and manipulation
+    - Communication channels
+
+    Subclasses must implement:
+    - execute(): Perform the tool's primary function
+    - validate_parameters(): Validate input parameters before execution
+    """
+
+    def __init__(self, config: ToolConfig):
+        """
+        Initialize the base tool with configuration.
+
+        :param config: ToolConfig - Configuration for this tool instance.
+        """
+        self.config = config
+        self.name = config.name
+        self.description = config.description
+        self.category = config.category
+
+    @abstractmethod
+    async def execute(self, **kwargs) -> ToolResult:
+        """
+        Execute the tool with the given parameters.
+
+        This is the main entry point for tool execution. Subclasses implement
+        this method to define their specific functionality.
+
+        :param kwargs: Tool-specific parameters.
+        :return: ToolResult - Execution results including success status and output.
+        """
+        pass
+
+    @abstractmethod
+    def validate_parameters(self, parameters: Dict[str, Any]) -> bool:
+        """
+        Validate parameters before execution.
+
+        Subclasses implement this to check parameter correctness, types,
+        and required fields before attempting execution.
+
+        :param parameters: Dict[str, Any] - Parameters to validate.
+        :return: bool - True if valid, False otherwise.
+        """
+        pass
+
+    def get_schema(self) -> Dict[str, Any]:
+        """
+        Get the tool's schema definition.
+
+        Returns a structured representation of the tool including name,
+        description, category, and parameter schema for agent introspection.
+
+        :return: Dict[str, Any] - Tool schema with metadata and parameter definitions.
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "category": self.category.value,
+            "parameters": self.config.parameters_schema,
+        }
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}(name='{self.name}', category='{self.category.value}')>"

pygeai_orchestration/core/common/__init__.py

@@ -0,0 +1,18 @@
+from .message import Message, MessageRole, Conversation
+from .context import Context, ContextManager
+from .state import State, StateStatus, StateManager
+from .memory import Memory, MemoryEntry, MemoryStore
+
+__all__ = [
+    "Message",
+    "MessageRole",
+    "Conversation",
+    "Context",
+    "ContextManager",
+    "State",
+    "StateStatus",
+    "StateManager",
+    "Memory",
+    "MemoryEntry",
+    "MemoryStore",
+]