pygeai-orchestration 0.1.0b2__py3-none-any.whl

pygeai_orchestration/patterns/reflection.py

@@ -0,0 +1,134 @@
+from typing import Any, Dict, Optional
+from ..core.base import BasePattern, PatternConfig, PatternResult, PatternType
+from ..core.common import Message, MessageRole, Conversation, State, StateStatus
+from ..core.utils import get_logger
+
+logger = get_logger()
+
+
+class ReflectionPattern(BasePattern):
+    """
+    Reflection pattern for iterative self-improvement of agent responses.
+
+    This pattern enables agents to critique and refine their own outputs through
+    multiple iterations. Each iteration consists of generating a response, reflecting
+    on its quality, and producing an improved version. The process continues until
+    convergence or max_iterations is reached.
+
+    The reflection pattern is particularly effective for tasks requiring high-quality
+    outputs such as content creation, analysis, and problem-solving where iterative
+    refinement leads to better results.
+    """
+
+    def __init__(
+        self, agent, config: Optional[PatternConfig] = None, reflection_prompt: Optional[str] = None
+    ):
+        """
+        Initialize the Reflection pattern.
+
+        :param agent: BaseAgent - The agent to use for generation and reflection.
+        :param config: Optional[PatternConfig] - Pattern configuration. If None, uses default with max_iterations=3.
+        :param reflection_prompt: Optional[str] - Custom reflection prompt. If None, uses default prompt.
+        """
+        if config is None:
+            config = PatternConfig(
+                name="reflection", pattern_type=PatternType.REFLECTION, max_iterations=3
+            )
+        super().__init__(config)
+        self.agent = agent
+        self.reflection_prompt = reflection_prompt or (
+            "Review your previous response. Identify any issues, inaccuracies, or areas for improvement. "
+            "Provide a refined and improved version of your response."
+        )
+        self._conversation = Conversation(id=f"reflection-{id(self)}")
+        self._state = State()
+
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> PatternResult:
+        """
+        Execute the reflection pattern on the given task.
+
+        The method iteratively improves the agent's response through self-reflection.
+        Each iteration generates a response, reflects on it, and produces an improved
+        version. The process stops when max_iterations is reached or convergence is detected.
+
+        :param task: str - The task or prompt to execute.
+        :param context: Optional[Dict[str, Any]] - Additional context for execution. Defaults to None.
+        :return: PatternResult - Contains success status, final refined result, iteration count, and metadata.
+        :raises ValueError: If task is empty or None.
+
+        Example:
+            >>> pattern = ReflectionPattern(agent=my_agent)
+            >>> result = await pattern.execute("Explain quantum computing in simple terms")
+            >>> print(f"Result after {result.iterations} iterations: {result.result}")
+        """
+        self.reset()
+        self._state.update_status(StateStatus.RUNNING)
+
+        logger.info(f"Starting reflection pattern for task: {task[:50]}...")
+
+        try:
+            self._conversation.add_message(Message(role=MessageRole.USER, content=task))
+
+            current_response = None
+
+            while self.current_iteration < self.config.max_iterations:
+                self.increment_iteration()
+                logger.debug(
+                    f"Reflection iteration {self.current_iteration}/{self.config.max_iterations}"
+                )
+
+                state_data = {
+                    "iteration": self.current_iteration,
+                    "task": task,
+                    "current_response": current_response,
+                }
+
+                step_result = await self.step(state_data)
+                current_response = step_result.get("response")
+
+                if step_result.get("should_stop", False):
+                    logger.info(f"Reflection converged at iteration {self.current_iteration}")
+                    break
+
+            self._state.update_status(StateStatus.COMPLETED)
+
+            return PatternResult(
+                success=True,
+                result=current_response,
+                iterations=self.current_iteration,
+                metadata={
+                    "conversation_length": len(self._conversation.messages),
+                    "final_iteration": self.current_iteration,
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"Reflection pattern failed: {str(e)}")
+            self._state.update_status(StateStatus.FAILED)
+            return PatternResult(
+                success=False, result=None, iterations=self.current_iteration, error=str(e)
+            )
+
+    async def step(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        iteration = state.get("iteration", 1)
+        task = state.get("task")
+        current_response = state.get("current_response")
+
+        if iteration == 1:
+            logger.debug("Generating initial response")
+            response = await self.agent.generate(task)
+        else:
+            logger.debug(f"Reflecting on iteration {iteration}")
+            reflection_request = (
+                f"Previous response:\n{current_response}\n\n{self.reflection_prompt}"
+            )
+            response = await self.agent.generate(reflection_request)
+
+        self._conversation.add_message(Message(role=MessageRole.ASSISTANT, content=response))
+
+        should_stop = iteration >= self.config.max_iterations
+
+        return {"response": response, "should_stop": should_stop, "iteration": iteration}
+
+    def get_conversation(self) -> Conversation:
+        return self._conversation

pygeai_orchestration/patterns/tool_use.py

@@ -0,0 +1,170 @@
+from typing import Any, Dict, List, Optional
+from ..core.base import BasePattern, BaseTool, PatternConfig, PatternResult, PatternType
+from ..core.common import Message, MessageRole, Conversation, State, StateStatus
+from ..core.utils import get_logger
+
+logger = get_logger()
+
+
+class ToolUsePattern(BasePattern):
+    """
+    Tool use pattern for agent interaction with external tools.
+
+    This pattern enables agents to leverage external tools and APIs to complete
+    tasks that require external information or capabilities. The agent can
+    intelligently select and use appropriate tools based on the task requirements,
+    parse tool results, and integrate them into the final response.
+
+    The tool use pattern is essential for tasks requiring:
+    - External data retrieval (APIs, databases, search engines)
+    - Computations (calculators, data processors)
+    - Actions (file operations, notifications, commands)
+
+    The pattern orchestrates a conversation loop where the agent can:
+    1. Analyze the task and available tools
+    2. Select and invoke appropriate tools with parameters
+    3. Process tool results and integrate them
+    4. Iterate until the task is complete
+    """
+
+    def __init__(self, agent, tools: List[BaseTool], config: Optional[PatternConfig] = None):
+        """
+        Initialize the Tool Use pattern.
+
+        :param agent: BaseAgent - The agent to use for tool selection and result processing.
+        :param tools: List[BaseTool] - List of available tools the agent can use.
+        :param config: Optional[PatternConfig] - Pattern configuration. If None, uses default with max_iterations=5.
+        """
+        if config is None:
+            config = PatternConfig(
+                name="tool_use", pattern_type=PatternType.TOOL_USE, max_iterations=5
+            )
+        super().__init__(config)
+        self.agent = agent
+        self.tools = {tool.name: tool for tool in tools}
+        self._conversation = Conversation(id=f"tool-use-{id(self)}")
+        self._state = State()
+
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> PatternResult:
+        """
+        Execute the tool use pattern on the given task.
+
+        The method enables the agent to iteratively select and use tools to complete
+        the task. The agent receives descriptions of available tools and can invoke
+        them by responding with specific commands. Tool results are integrated into
+        the conversation until the agent provides a final answer.
+
+        :param task: str - The task or question to execute with tool assistance.
+        :param context: Optional[Dict[str, Any]] - Additional context for execution. Defaults to None.
+        :return: PatternResult - Contains success status, final answer, tools used, and metadata.
+        :raises ToolExecutionError: If a tool execution fails.
+
+        Example:
+            >>> tools = [CalculatorTool(), SearchTool()]
+            >>> pattern = ToolUsePattern(agent=my_agent, tools=tools)
+            >>> result = await pattern.execute("What is 15% of 240?")
+            >>> print(f"Answer: {result.result}, Tools used: {result.metadata['tools_used']}")
+        """
+        self.reset()
+        self._state.update_status(StateStatus.RUNNING)
+
+        logger.info(f"Starting tool use pattern for task: {task[:50]}...")
+
+        try:
+            tools_description = self._get_tools_description()
+            system_prompt = (
+                f"You have access to the following tools:\n{tools_description}\n\n"
+                "To use a tool, respond with: TOOL_CALL: <tool_name> <parameters>\n"
+                "When you have the final answer, respond with: FINAL_ANSWER: <answer>"
+            )
+
+            self._conversation.add_message(Message(role=MessageRole.SYSTEM, content=system_prompt))
+            self._conversation.add_message(Message(role=MessageRole.USER, content=task))
+
+            final_answer = None
+
+            while self.current_iteration < self.config.max_iterations:
+                self.increment_iteration()
+                logger.debug(
+                    f"Tool use iteration {self.current_iteration}/{self.config.max_iterations}"
+                )
+
+                state_data = {
+                    "iteration": self.current_iteration,
+                    "task": task,
+                    "conversation": self._conversation.to_dict_list(),
+                }
+
+                step_result = await self.step(state_data)
+
+                if step_result.get("is_final"):
+                    final_answer = step_result.get("answer")
+                    logger.info(f"Tool use completed at iteration {self.current_iteration}")
+                    break
+
+            self._state.update_status(StateStatus.COMPLETED)
+
+            return PatternResult(
+                success=True,
+                result=final_answer or "No final answer provided",
+                iterations=self.current_iteration,
+                metadata={
+                    "tools_used": step_result.get("tools_used", []),
+                    "conversation_length": len(self._conversation.messages),
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"Tool use pattern failed: {str(e)}")
+            self._state.update_status(StateStatus.FAILED)
+            return PatternResult(
+                success=False, result=None, iterations=self.current_iteration, error=str(e)
+            )
+
+    async def step(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        conversation = state.get("conversation", [])
+        conversation_str = "\n".join([f"{m['role']}: {m['content']}" for m in conversation[-5:]])
+
+        response = await self.agent.generate(conversation_str)
+
+        if response.startswith("TOOL_CALL:"):
+            tool_call = response[len("TOOL_CALL:") :].strip()
+            parts = tool_call.split(maxsplit=1)
+            tool_name = parts[0]
+            tool_params = parts[1] if len(parts) > 1 else ""
+
+            logger.debug(f"Calling tool: {tool_name} with params: {tool_params}")
+
+            if tool_name in self.tools:
+                tool_result = await self.tools[tool_name].execute(input=tool_params)
+                result_msg = f"Tool '{tool_name}' result: {tool_result.result}"
+                self._conversation.add_message(Message(role=MessageRole.TOOL, content=result_msg))
+
+                return {
+                    "is_final": False,
+                    "answer": None,
+                    "tool_called": tool_name,
+                    "tools_used": [tool_name],
+                }
+            else:
+                error_msg = f"Unknown tool: {tool_name}"
+                self._conversation.add_message(Message(role=MessageRole.SYSTEM, content=error_msg))
+                return {"is_final": False, "answer": None, "tools_used": []}
+
+        elif response.startswith("FINAL_ANSWER:"):
+            answer = response[len("FINAL_ANSWER:") :].strip()
+            self._conversation.add_message(Message(role=MessageRole.ASSISTANT, content=answer))
+            return {"is_final": True, "answer": answer, "tools_used": []}
+
+        else:
+            self._conversation.add_message(Message(role=MessageRole.ASSISTANT, content=response))
+            return {"is_final": False, "answer": None, "tools_used": []}
+
+    def _get_tools_description(self) -> str:
+        descriptions = []
+        for tool in self.tools.values():
+            descriptions.append(f"- {tool.name}: {tool.description}")
+        return "\n".join(descriptions)
+
+    def get_conversation(self) -> Conversation:
+        return self._conversation

pygeai_orchestration/tests/__init__.py

@@ -0,0 +1 @@
+"""Package module."""

pygeai_orchestration/tests/test_base_classes.py

@@ -0,0 +1,187 @@
+import unittest
+import asyncio
+from pygeai_orchestration import (
+    AgentConfig,
+    BaseAgent,
+    PatternConfig,
+    BasePattern,
+    PatternType,
+    PatternResult,
+    OrchestratorConfig,
+    BaseOrchestrator,
+    ToolConfig,
+    BaseTool,
+    ToolResult,
+    ToolCategory
+)
+
+
+class ConcreteAgent(BaseAgent):
+    """Concrete implementation for testing."""
+
+    async def execute(self, task: str, context=None):
+        return {"success": True, "result": "Executed"}
+
+    async def generate(self, prompt: str, **kwargs):
+        return "Generated response"
+
+
+class ConcretePattern(BasePattern):
+    """Concrete implementation for testing."""
+
+    async def execute(self, task: str, context=None):
+        return PatternResult(success=True, result="Done", iterations=1)
+
+    async def step(self, state):
+        return {"status": "ok"}
+
+
+class ConcreteOrchestrator(BaseOrchestrator):
+    """Concrete implementation for testing."""
+
+    async def orchestrate(self, task: str, pattern: str, context=None):
+        return PatternResult(success=True, result="Orchestrated", iterations=1)
+
+    async def coordinate_agents(self, agents, task: str):
+        return {"success": True, "results": {}}
+
+
+class ConcreteTool(BaseTool):
+    """Concrete implementation for testing."""
+
+    async def execute(self, **kwargs):
+        return ToolResult(success=True, result="Tool executed")
+
+    def validate_parameters(self, parameters):
+        return True
+
+
+class TestBaseAgent(unittest.TestCase):
+
+    def test_creation(self):
+        config = AgentConfig(name="test-agent", model="gpt-4")
+        agent = ConcreteAgent(config)
+
+        self.assertEqual(agent.name, "test-agent")
+        self.assertEqual(agent.config.model, "gpt-4")
+        self.assertEqual(len(agent.get_history()), 0)
+
+    def test_history(self):
+        config = AgentConfig(name="test-agent", model="gpt-4")
+        agent = ConcreteAgent(config)
+
+        agent.add_to_history({"test": "data"})
+        self.assertEqual(len(agent.get_history()), 1)
+
+        agent.clear_history()
+        self.assertEqual(len(agent.get_history()), 0)
+
+    def test_execute(self):
+        config = AgentConfig(name="test-agent", model="gpt-4")
+        agent = ConcreteAgent(config)
+
+        result = asyncio.run(agent.execute("Test task"))
+        self.assertTrue(result["success"])
+
+
+class TestBasePattern(unittest.TestCase):
+
+    def test_creation(self):
+        config = PatternConfig(
+            name="test-pattern",
+            pattern_type=PatternType.REFLECTION,
+            max_iterations=5
+        )
+        pattern = ConcretePattern(config)
+
+        self.assertEqual(pattern.name, "test-pattern")
+        self.assertEqual(pattern.pattern_type, PatternType.REFLECTION)
+        self.assertEqual(pattern.current_iteration, 0)
+
+    def test_iteration_tracking(self):
+        config = PatternConfig(name="test", pattern_type=PatternType.REFLECTION)
+        pattern = ConcretePattern(config)
+
+        self.assertEqual(pattern.current_iteration, 0)
+        pattern.increment_iteration()
+        self.assertEqual(pattern.current_iteration, 1)
+        pattern.reset()
+        self.assertEqual(pattern.current_iteration, 0)
+
+    def test_execute(self):
+        config = PatternConfig(name="test", pattern_type=PatternType.REFLECTION)
+        pattern = ConcretePattern(config)
+
+        result = asyncio.run(pattern.execute("Test"))
+        self.assertTrue(result.success)
+        self.assertEqual(result.iterations, 1)
+
+
+class TestBaseOrchestrator(unittest.TestCase):
+
+    def test_creation(self):
+        config = OrchestratorConfig(name="test-orchestrator")
+        orch = ConcreteOrchestrator(config)
+
+        self.assertEqual(orch.name, "test-orchestrator")
+        self.assertEqual(len(orch.list_agents()), 0)
+        self.assertEqual(len(orch.list_patterns()), 0)
+
+    def test_register_agent(self):
+        config = OrchestratorConfig(name="test-orchestrator")
+        orch = ConcreteOrchestrator(config)
+
+        agent_config = AgentConfig(name="agent1", model="gpt-4")
+        agent = ConcreteAgent(agent_config)
+        orch.register_agent(agent)
+
+        self.assertEqual(len(orch.list_agents()), 1)
+        self.assertIsNotNone(orch.get_agent("agent1"))
+
+    def test_register_pattern(self):
+        config = OrchestratorConfig(name="test-orchestrator")
+        orch = ConcreteOrchestrator(config)
+
+        pattern_config = PatternConfig(name="pattern1", pattern_type=PatternType.REFLECTION)
+        pattern = ConcretePattern(pattern_config)
+        orch.register_pattern(pattern)
+
+        self.assertEqual(len(orch.list_patterns()), 1)
+        self.assertIsNotNone(orch.get_pattern("pattern1"))
+
+
+class TestBaseTool(unittest.TestCase):
+
+    def test_creation(self):
+        config = ToolConfig(
+            name="test-tool",
+            description="A test tool",
+            category=ToolCategory.CUSTOM
+        )
+        tool = ConcreteTool(config)
+
+        self.assertEqual(tool.name, "test-tool")
+        self.assertEqual(tool.category, ToolCategory.CUSTOM)
+
+    def test_schema(self):
+        config = ToolConfig(
+            name="test-tool",
+            description="A test tool",
+            category=ToolCategory.SEARCH
+        )
+        tool = ConcreteTool(config)
+
+        schema = tool.get_schema()
+        self.assertEqual(schema["name"], "test-tool")
+        self.assertEqual(schema["category"], "search")
+
+    def test_execute(self):
+        config = ToolConfig(name="test-tool", description="Test", category=ToolCategory.CUSTOM)
+        tool = ConcreteTool(config)
+
+        result = asyncio.run(tool.execute())
+        self.assertTrue(result.success)
+
+
+if __name__ == '__main__':
+    unittest.main()

pygeai_orchestration/tests/test_cache.py

@@ -0,0 +1,184 @@
+import time
+import unittest
+
+from pygeai_orchestration.core.utils.cache import CacheEntry, LRUCache, PatternCache
+
+
+class TestCacheEntry(unittest.TestCase):
+    def test_cache_entry_creation(self):
+        entry = CacheEntry("test_value")
+        self.assertEqual(entry.value, "test_value")
+        self.assertEqual(entry.access_count, 0)
+        self.assertIsNotNone(entry.created_at)
+        self.assertIsNone(entry.ttl)
+
+    def test_cache_entry_with_ttl(self):
+        entry = CacheEntry("test_value", ttl=1.0)
+        self.assertEqual(entry.ttl, 1.0)
+        self.assertFalse(entry.is_expired())
+
+    def test_cache_entry_expiration(self):
+        entry = CacheEntry("test_value", ttl=0.1)
+        self.assertFalse(entry.is_expired())
+        time.sleep(0.2)
+        self.assertTrue(entry.is_expired())
+
+    def test_cache_entry_access(self):
+        entry = CacheEntry("test_value")
+        self.assertEqual(entry.access_count, 0)
+        value = entry.access()
+        self.assertEqual(value, "test_value")
+        self.assertEqual(entry.access_count, 1)
+        entry.access()
+        self.assertEqual(entry.access_count, 2)
+
+
+class TestLRUCache(unittest.TestCase):
+    def setUp(self):
+        self.cache = LRUCache(max_size=3)
+
+    def test_cache_creation(self):
+        cache = LRUCache(max_size=10, default_ttl=60.0)
+        self.assertEqual(cache.max_size, 10)
+        self.assertEqual(cache.default_ttl, 60.0)
+        self.assertEqual(cache.size(), 0)
+
+    def test_set_and_get(self):
+        self.cache.set("key1", "value1")
+        value = self.cache.get("key1")
+        self.assertEqual(value, "value1")
+
+    def test_cache_miss(self):
+        value = self.cache.get("nonexistent")
+        self.assertIsNone(value)
+
+    def test_lru_eviction(self):
+        self.cache.set("key1", "value1")
+        self.cache.set("key2", "value2")
+        self.cache.set("key3", "value3")
+        self.cache.set("key4", "value4")
+
+        self.assertIsNone(self.cache.get("key1"))
+        self.assertEqual(self.cache.get("key2"), "value2")
+        self.assertEqual(self.cache.get("key3"), "value3")
+        self.assertEqual(self.cache.get("key4"), "value4")
+
+    def test_lru_ordering(self):
+        self.cache.set("key1", "value1")
+        self.cache.set("key2", "value2")
+        self.cache.set("key3", "value3")
+
+        self.cache.get("key1")
+
+        self.cache.set("key4", "value4")
+
+        self.assertIsNone(self.cache.get("key2"))
+        self.assertEqual(self.cache.get("key1"), "value1")
+
+    def test_ttl_expiration(self):
+        cache = LRUCache(max_size=10, default_ttl=0.1)
+        cache.set("key1", "value1")
+        self.assertEqual(cache.get("key1"), "value1")
+
+        time.sleep(0.2)
+        self.assertIsNone(cache.get("key1"))
+
+    def test_custom_ttl(self):
+        self.cache.set("key1", "value1", ttl=0.1)
+        self.cache.set("key2", "value2", ttl=10.0)
+
+        time.sleep(0.2)
+        self.assertIsNone(self.cache.get("key1"))
+        self.assertEqual(self.cache.get("key2"), "value2")
+
+    def test_invalidate(self):
+        self.cache.set("key1", "value1")
+        self.assertTrue(self.cache.invalidate("key1"))
+        self.assertIsNone(self.cache.get("key1"))
+        self.assertFalse(self.cache.invalidate("key1"))
+
+    def test_clear(self):
+        self.cache.set("key1", "value1")
+        self.cache.set("key2", "value2")
+        self.assertEqual(self.cache.size(), 2)
+
+        self.cache.clear()
+        self.assertEqual(self.cache.size(), 0)
+        self.assertIsNone(self.cache.get("key1"))
+
+    def test_cache_stats(self):
+        self.cache.get("miss1")
+        self.cache.get("miss2")
+
+        self.cache.set("key1", "value1")
+        self.cache.get("key1")
+        self.cache.get("key1")
+
+        stats = self.cache.get_stats()
+        self.assertEqual(stats["hits"], 2)
+        self.assertEqual(stats["misses"], 2)
+        self.assertEqual(stats["total_requests"], 4)
+        self.assertEqual(stats["hit_rate"], 50.0)
+
+    def test_complex_key(self):
+        key = {"param1": "value1", "param2": [1, 2, 3]}
+        self.cache.set(key, "result")
+        value = self.cache.get(key)
+        self.assertEqual(value, "result")
+
+    def test_key_generation_consistency(self):
+        key1 = {"b": 2, "a": 1}
+        key2 = {"a": 1, "b": 2}
+
+        self.cache.set(key1, "value1")
+        value = self.cache.get(key2)
+        self.assertEqual(value, "value1")
+
+
+class TestPatternCache(unittest.TestCase):
+    def setUp(self):
+        PatternCache.reset()
+
+    def tearDown(self):
+        PatternCache.reset()
+
+    def test_singleton_pattern(self):
+        cache1 = PatternCache()
+        cache2 = PatternCache()
+        self.assertIs(cache1, cache2)
+
+    def test_initialize(self):
+        pattern_cache = PatternCache()
+        pattern_cache.initialize(max_size=50, default_ttl=120.0)
+
+        cache = pattern_cache.get_cache()
+        self.assertEqual(cache.max_size, 50)
+        self.assertEqual(cache.default_ttl, 120.0)
+
+    def test_auto_initialize(self):
+        pattern_cache = PatternCache()
+        cache = pattern_cache.get_cache()
+        self.assertIsNotNone(cache)
+        self.assertEqual(cache.max_size, 100)
+
+    def test_clear(self):
+        pattern_cache = PatternCache()
+        cache = pattern_cache.get_cache()
+        cache.set("key1", "value1")
+
+        pattern_cache.clear()
+        self.assertEqual(cache.size(), 0)
+
+    def test_reset(self):
+        pattern_cache1 = PatternCache()
+        pattern_cache1.initialize(max_size=10)
+
+        PatternCache.reset()
+
+        pattern_cache2 = PatternCache()
+        cache = pattern_cache2.get_cache()
+        self.assertEqual(cache.max_size, 100)
+
+
+if __name__ == "__main__":
+    unittest.main()