clap-agents 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

clap/multiagent_pattern/agent.py

@@ -1,20 +1,50 @@
 
-
 import asyncio
 import json
 from textwrap import dedent
-from typing import Any, List, Optional
+from typing import Any, List, Optional, Dict 
 
 from clap.llm_services.base import LLMServiceInterface
-from clap.llm_services.groq_service import GroqService
+from clap.llm_services.groq_service import GroqService 
+
 from clap.mcp_client.client import MCPClientManager
-from clap.react_pattern.react_agent import ReactAgent
+
 from clap.tool_pattern.tool import Tool
 
+from clap.vector_stores.base import VectorStoreInterface
+
+
+
+
+VECTOR_QUERY_TOOL_SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "vector_query",
+        "description": "Queries the configured vector store for relevant information based on the input query text. Use this to find context from stored documents before answering complex questions or summarizing information.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The natural language query text to search for relevant documents."
+                },
+                "top_k": {
+                    "type": "integer",
+                    "description": "The maximum number of relevant document chunks to retrieve. Defaults to 3.",
+                    "default": 3
+                },
+                
+            },
+            "required": ["query"]
+        }
+    }
+}
+
+
 class Agent:
     """
     Represents an AI agent using a configurable LLM Service.
-    Can work in a team and use local or remote MCP tools.
+    Can work in a team, use local/remote MCP tools, and optionally a vector store.
 
     Args:
         name (str): Agent name.
@@ -22,22 +52,28 @@ class Agent:
         task_description (str): Description of the agent's specific task.
         task_expected_output (str): Expected output format.
         tools (Optional[List[Tool]]): Local tools for the agent.
-        llm (str): Model identifier string (passed to llm_service).
+        model (str): Model identifier string (passed to llm_service).
         llm_service (Optional[LLMServiceInterface]): Service for LLM calls (defaults to GroqService).
         mcp_manager (Optional[MCPClientManager]): Shared MCP client manager.
         mcp_server_names (Optional[List[str]]): MCP servers this agent uses.
+        vector_store (Optional[VectorStoreInterface]): Vector store instance for RAG. 
+        # embedding_function(Optional[EmbeddingFunction]): EF if needed by agent. 
+
     """
     def __init__(
         self,
         name: str,
         backstory: str,
-        task_description: str,
+        task_description: str = "No specific task assigned; await runtime user message.",
         task_expected_output: str = "",
         tools: Optional[List[Tool]] = None,
         model: str = "llama-3.3-70b-versatile", 
         llm_service: Optional[LLMServiceInterface] = None,
         mcp_manager: Optional[MCPClientManager] = None,
         mcp_server_names: Optional[List[str]] = None,
+        vector_store: Optional[VectorStoreInterface] = None, 
+        # embedding_function: Optional[EmbeddingFunction] = None,
+
     ):
         self.name = name
         self.backstory = backstory
@@ -45,36 +81,41 @@ class Agent:
         self.task_expected_output = task_expected_output
         self.mcp_manager = mcp_manager
         self.mcp_server_names = mcp_server_names or []
+        self.local_tools = tools or [] 
+
+        self.vector_store = vector_store
+        # self.embedding_function = embedding_function 
 
         llm_service_instance = llm_service or GroqService()
 
+       
+        from clap.react_pattern.react_agent import ReactAgent 
         self.react_agent = ReactAgent(
+            agent_name=self.name, 
             llm_service=llm_service_instance,
             model=model,
             system_prompt=self.backstory,
-            tools=tools or [],
+            tools=self.local_tools, 
             mcp_manager=self.mcp_manager,
-            mcp_server_names=self.mcp_server_names
+            mcp_server_names=self.mcp_server_names,
+            vector_store=self.vector_store 
         )
 
         self.dependencies: List['Agent'] = []
         self.dependents: List['Agent'] = []
         self.received_context: dict[str, Any] = {}
 
-        from clap.multiagent_pattern.team import Team
+        from clap.multiagent_pattern.team import Team 
         Team.register_agent(self)
 
-   
+
     def __repr__(self): return f"{self.name}"
 
     def __rshift__(self, other: 'Agent') -> 'Agent': self.add_dependent(other); return other
-
     def __lshift__(self, other: 'Agent') -> 'Agent': self.add_dependency(other); return other
-
     def __rrshift__(self, other: List['Agent'] | 'Agent'): self.add_dependency(other); return self
-
     def __rlshift__(self, other: List['Agent'] | 'Agent'): self.add_dependent(other); return self
-    
+
     def add_dependency(self, other: 'Agent' | List['Agent']):
         AgentClass = type(self)
         if isinstance(other, AgentClass):
@@ -95,34 +136,66 @@ class Agent:
                 if self not in item.dependencies: item.dependencies.append(self)
                 if item not in self.dependents: self.dependents.append(item)
         else: raise TypeError("The dependent must be an instance or list of Agent.")
-    def receive_context(self, sender_name: str, input_data: Any): self.received_context[sender_name] = input_data
+
+    def receive_context(self, sender_name: str, input_data: Any):
+        self.received_context[sender_name] = input_data
+
     def create_prompt(self) -> str:
-        context_str = "\n---\n".join(f"Context from {name}:\n{json.dumps(data, indent=2) if isinstance(data, dict) else str(data)}" for name, data in self.received_context.items())
-        if not context_str: context_str = "No context received from other agents."
+        """Creates the initial prompt for the agent's task execution."""
+        context_str = "\n---\n".join(
+            f"Context from {name}:\n{json.dumps(data, indent=2, ensure_ascii=False) if isinstance(data, dict) else str(data)}"
+            for name, data in self.received_context.items()
+        )
+        if not context_str:
+            context_str = "No context received from other agents."
+
+        vector_store_info = ""
+        user_query = self.task_description 
+
+        if self.vector_store:
+            vector_store_info = "\nVector Store Available: Use the 'vector_query' tool with the User Query below to find relevant context before answering factual questions."
+
+        task_info = f"""
+        User Query: {user_query}
+        Task: Answer the User Query. {vector_store_info or ''} Use context from other agents if provided.
+        Expected Output: {self.task_expected_output or 'Produce a meaningful response to complete the task.'}
+        """.strip()
+
         prompt = dedent(f"""
-        You are an AI agent named {self.name}. Your backstory: {self.backstory}
-        You are part of a team of agents working together to complete a task.
-        Your immediate task is described below. Use the provided context from other agents if relevant.
+        Agent: {self.name}
+        Persona: {self.backstory}
+        Team Context: {context_str}
+
+        {task_info}
+
+        Execute now following the ReAct pattern. If using 'vector_query', use the User Query text as the 'query' argument.
+        """).strip()
+        return prompt
 
-        <task_description>
-        {self.task_description}
-        </task_description>
+    async def run(self, user_msg: Optional[str] = None) -> dict[str, Any]: 
+        """Runs the agent's task using its configured ReactAgent.
+        """
+        print(f"Agent {self.name}: Preparing to run...")
 
-        <task_expected_output>
-        {self.task_expected_output or 'Produce a meaningful response to complete the task.'}
-        </task_expected_output>
+        current_task = user_msg if user_msg is not None else self.task_description
+        if not user_msg and self.task_description == "No specific task assigned; await runtime user message.":
+             print(f"Agent {self.name}: Warning - Running without a specific user_msg or a meaningful pre-set task_description.")
 
-        <context>
-        {context_str}
-        </context>
+        
+        original_task_description = self.task_description
+        self.task_description = current_task 
 
-        Now, execute your task based on the description, context, and expected output. Your response:
-        """).strip(); return prompt
-    async def run(self) -> dict[str, Any]:
         msg = self.create_prompt()
-        raw_output = await self.react_agent.run(user_msg=msg)
+        
+        self.task_description = original_task_description 
+
+        print(f"Agent {self.name}: Running ReactAgent...")
+        raw_output = await self.react_agent.run(user_msg=msg) 
         output_data = {"output": raw_output}
+
+        print(f"Agent {self.name}: Passing context to {len(self.dependents)} dependents...")
         for dependent in self.dependents:
             dependent.receive_context(self.name, output_data)
+
         return output_data
 

clap/multiagent_pattern/team.py

@@ -1,15 +1,22 @@
-# --- START OF team.py (Parallel Execution - Python 3.10 Compatible) ---
 
 import asyncio
 from collections import deque
-from typing import Any, Dict, List
-
+from typing import Any, Dict, List , Optional
 from colorama import Fore
-from graphviz import Digraph
-
 from clap.utils.logging import fancy_print
 from clap.multiagent_pattern.agent import Agent
 
+_GRAPHVIZ_AVAILABLE = False
+_Digraph_Placeholder_Type = Any 
+
+try:
+    from graphviz import Digraph as ImportedDigraph
+    from graphviz.backend import ExecutableNotFound as GraphvizExecutableNotFound 
+    _Digraph_Placeholder_Type = ImportedDigraph
+    _GRAPHVIZ_AVAILABLE = True
+except ImportError:
+    pass
+
 class Team:
     """
     A class representing a team of agents working together asynchronously.
@@ -26,7 +33,6 @@ class Team:
         self.agents: List[Agent] = []
         self.results: dict[str, Any] = {}
 
-    # __enter__, __exit__, add_agent, register_agent remain the same
     def __enter__(self): Team.current_team = self; return self
     def __exit__(self, exc_type, exc_val, exc_tb): Team.current_team = None
     def add_agent(self, agent: Agent):
@@ -35,7 +41,7 @@ class Team:
     def register_agent(agent: Agent):
         if Team.current_team is not None: Team.current_team.add_agent(agent)
 
-    # topological_sort and plot remain the same
+    
     def topological_sort(self) -> List[Agent]:
         in_degree: Dict[Agent, int] = {agent: 0 for agent in self.agents}
         adj: Dict[Agent, List[Agent]] = {agent: [] for agent in self.agents}
@@ -71,15 +77,46 @@ class Team:
              )
         return sorted_agents
 
-    def plot(self):
-        dot = Digraph(format="png")
-        for agent in self.agents: dot.node(agent.name)
-        for agent in self.agents:
-             for dependent in agent.dependents:
-                  if dependent in self.agents: dot.edge(agent.name, dependent.name)
-        return dot
+    def plot(self) -> Optional[_Digraph_Placeholder_Type]:
+        """
+        Generates a visual representation of the agent team's dependency graph.
+        Requires the 'graphviz' Python library and the Graphviz system software to be installed.
+        If Graphviz is not available, prints a warning and returns None.
+
+        Returns:
+            Optional[graphviz.Digraph]: A Digraph object if successful, else None.
+        """
+        if not _GRAPHVIZ_AVAILABLE:
+            print(
+                f"{Fore.YELLOW}CLAP Warning: The 'graphviz' Python library is not installed. "
+                f"To use the plot() feature, please install it (e.g., pip install \"clap-agents[viz]\").{Fore.RESET}"
+            )
+            return None
+        
+        dot: Optional[_Digraph_Placeholder_Type] = None
+        try:
+            dot = _Digraph_Placeholder_Type(format="png") 
+            for agent in self.agents:
+                dot.node(agent.name) 
+            for agent in self.agents:
+                 for dependent in agent.dependents: 
+                      if dependent in self.agents: 
+                          dot.edge(agent.name, dependent.name) 
+            print(f"{Fore.GREEN}Team dependency graph created. To render, call .render() or .view() on the returned object.{Fore.RESET}")
+            return dot
+        except NameError: 
+            print(f"{Fore.YELLOW}CLAP Warning: Graphviz Digraph class not found (likely import issue). Plotting unavailable.{Fore.RESET}")
+            return None
+        except GraphvizExecutableNotFound:
+            print(
+                f"{Fore.RED}CLAP Error: Graphviz system software (dot executable) not found in PATH. "
+                f"Team.plot() requires it to generate images. Please install Graphviz for your OS and ensure 'dot' is in your PATH.{Fore.RESET}"
+            )
+            return None
+        except Exception as e:
+            print(f"{Fore.RED}CLAP Error: An unexpected error occurred during graph plotting: {e}{Fore.RESET}")
+            return None
 
-    # --- Modified run method for parallel execution (Python 3.10 compatible) ---
     async def run(self):
         """
         Runs all agents in the team asynchronously, executing them in parallel
@@ -93,29 +130,20 @@ class Team:
 
         self.results = {}
         agent_tasks: Dict[Agent, asyncio.Task] = {}
-        # Use a standard try/except block for Python 3.10 compatibility
         try:
-            # Use asyncio.gather for task management, requiring manual cancellation on error
             tasks_to_gather = []
             for agent in sorted_agents:
-                # Create the task but store it before adding to gather list
                 task = asyncio.create_task(self._run_agent_task(agent, agent_tasks))
                 agent_tasks[agent] = task
                 tasks_to_gather.append(task)
 
-            # Wait for all tasks to complete. If one fails, gather will raise that first exception.
             await asyncio.gather(*tasks_to_gather)
             print(f"{Fore.BLUE}--- All agent tasks finished ---{Fore.RESET}")
 
         except Exception as e:
-            # If any task failed, asyncio.gather raises the exception of the first task that failed.
             print(f"{Fore.RED}One or more agents failed during execution:{Fore.RESET}")
             print(f"{Fore.RED}- Error: {e}{Fore.RESET}")
-            # Note: With asyncio.gather, cancelling sibling tasks automatically
-            # when one fails requires more complex manual handling.
-            # For simplicity here, we let other tasks potentially run to completion
-            # or fail independently, but we report the first failure.
-            # Consider using anyio's TaskGroup if Python 3.11+ is an option for better cancellation.
+            
 
 
     async def _run_agent_task(self, agent: Agent, all_tasks: Dict[Agent, asyncio.Task]):
@@ -128,8 +156,7 @@ class Team:
         ]
         if dependency_tasks:
             print(f"{Fore.YELLOW}Agent {agent.name} waiting for dependencies: {[dep.name for dep in agent.dependencies if dep in all_tasks]}...{Fore.RESET}")
-            # Wait for all dependency tasks using asyncio.gather
-            # We want errors in dependencies to propagate, so return_exceptions=False
+            
             await asyncio.gather(*dependency_tasks)
             print(f"{Fore.GREEN}Agent {agent.name} dependencies met.{Fore.RESET}")
 
@@ -148,7 +175,5 @@ class Team:
             fancy_print(f"ERROR IN AGENT: {agent.name}")
             print(f"{Fore.RED}Agent {agent.name} failed: {e}{Fore.RESET}")
             self.results[agent.name] = {"error": str(e)}
-            # Re-raise the exception so asyncio.gather catches it
             raise
 
-# --- END OF team.py (Parallel Execution - Python 3.10 Compatible) ---