swarms 7.8.9__py3-none-any.whl → 7.9.0__py3-none-any.whl

swarms/structs/interactive_groupchat.py

@@ -1,5 +1,6 @@
 import re
-from typing import Callable, List, Union
+import random
+from typing import Callable, List, Union, Optional
 
 from loguru import logger
 
@@ -35,6 +36,91 @@ class InvalidTaskFormatError(InteractiveGroupChatError):
     pass
 
 
+class InvalidSpeakerFunctionError(InteractiveGroupChatError):
+    """Raised when an invalid speaker function is provided"""
+
+    pass
+
+
+# Built-in speaker functions
+def round_robin_speaker(
+    agents: List[str], current_index: int = 0
+) -> str:
+    """
+    Round robin speaker function that cycles through agents in order.
+
+    Args:
+        agents: List of agent names
+        current_index: Current position in the cycle
+
+    Returns:
+        Next agent name in the round robin sequence
+    """
+    if not agents:
+        raise ValueError("No agents provided for round robin")
+    return agents[current_index % len(agents)]
+
+
+def random_speaker(agents: List[str], **kwargs) -> str:
+    """
+    Random speaker function that selects agents randomly.
+
+    Args:
+        agents: List of agent names
+        **kwargs: Additional arguments (ignored)
+
+    Returns:
+        Randomly selected agent name
+    """
+    if not agents:
+        raise ValueError("No agents provided for random selection")
+    return random.choice(agents)
+
+
+def priority_speaker(
+    agents: List[str], priorities: dict, **kwargs
+) -> str:
+    """
+    Priority-based speaker function that selects agents based on priority weights.
+
+    Args:
+        agents: List of agent names
+        priorities: Dictionary mapping agent names to priority weights
+        **kwargs: Additional arguments (ignored)
+
+    Returns:
+        Selected agent name based on priority weights
+    """
+    if not agents:
+        raise ValueError("No agents provided for priority selection")
+
+    # Filter agents that exist in the priorities dict
+    available_agents = [
+        agent for agent in agents if agent in priorities
+    ]
+    if not available_agents:
+        # Fallback to random if no priorities match
+        return random.choice(agents)
+
+    # Calculate total weight
+    total_weight = sum(
+        priorities[agent] for agent in available_agents
+    )
+    if total_weight == 0:
+        return random.choice(available_agents)
+
+    # Select based on weighted probability
+    rand_val = random.uniform(0, total_weight)
+    current_weight = 0
+
+    for agent in available_agents:
+        current_weight += priorities[agent]
+        if rand_val <= current_weight:
+            return agent
+
+    return available_agents[-1]  # Fallback
+
+
 class InteractiveGroupChat:
     """
     An interactive group chat system that enables conversations with multiple agents using @mentions.
@@ -49,6 +135,8 @@ class InteractiveGroupChat:
         max_loops (int): Maximum number of conversation turns
         conversation (Conversation): Stores the chat history
         agent_map (Dict[str, Union[Agent, Callable]]): Mapping of agent names to their instances
+        speaker_function (Callable): Function to determine speaking order
+        speaker_state (dict): State for speaker functions that need it
 
     Args:
         name (str, optional): Name of the group chat. Defaults to "InteractiveGroupChat".
@@ -57,6 +145,8 @@ class InteractiveGroupChat:
         max_loops (int, optional): Maximum conversation turns. Defaults to 1.
         output_type (str, optional): Type of output format. Defaults to "string".
         interactive (bool, optional): Whether to enable interactive terminal mode. Defaults to False.
+        speaker_function (Callable, optional): Function to determine speaking order. Defaults to round_robin_speaker.
+        speaker_state (dict, optional): Initial state for speaker function. Defaults to empty dict.
 
     Raises:
         ValueError: If invalid initialization parameters are provided
@@ -71,6 +161,8 @@ class InteractiveGroupChat:
         max_loops: int = 1,
         output_type: str = "string",
         interactive: bool = False,
+        speaker_function: Optional[Callable] = None,
+        speaker_state: Optional[dict] = None,
     ):
         self.id = id
         self.name = name
@@ -80,6 +172,15 @@ class InteractiveGroupChat:
         self.output_type = output_type
         self.interactive = interactive
 
+        # Speaker function configuration
+        self.speaker_function = (
+            speaker_function or round_robin_speaker
+        )
+        self.speaker_state = speaker_state or {"current_index": 0}
+
+        # Validate speaker function
+        self._validate_speaker_function()
+
         # Initialize conversation history
         self.conversation = Conversation(time_enabled=True)
 
@@ -96,6 +197,32 @@ class InteractiveGroupChat:
         self._setup_conversation_context()
         self._update_agent_prompts()
 
+    def _validate_speaker_function(self) -> None:
+        """
+        Validates the speaker function.
+
+        Raises:
+            InvalidSpeakerFunctionError: If the speaker function is invalid
+        """
+        if not callable(self.speaker_function):
+            raise InvalidSpeakerFunctionError(
+                "Speaker function must be callable"
+            )
+
+        # Test the speaker function with a dummy list
+        try:
+            test_result = self.speaker_function(
+                ["test_agent"], **self.speaker_state
+            )
+            if not isinstance(test_result, str):
+                raise InvalidSpeakerFunctionError(
+                    "Speaker function must return a string"
+                )
+        except Exception as e:
+            raise InvalidSpeakerFunctionError(
+                f"Speaker function validation failed: {e}"
+            )
+
     def _validate_initialization(self) -> None:
         """
         Validates the group chat configuration.
@@ -150,6 +277,26 @@ class InteractiveGroupChat:
                     }
                 )
 
+        # Create the enhanced prompt that teaches agents how to use @mentions
+        mention_instruction = """
+        
+IMPORTANT: You are part of a collaborative group chat where you can interact with other agents using @mentions.
+
+-COLLABORATIVE RESPONSE PROTOCOL:
+1. FIRST: Read and understand all previous responses from other agents
+2. ACKNOWLEDGE: Reference and acknowledge what other agents have said
+3. BUILD UPON: Add your perspective while building upon their insights
+4. MENTION: Use @agent_name to call on other agents when needed
+
+HOW TO MENTION OTHER AGENTS:
+- Use @agent_name to mention another agent in your response
+- You can mention multiple agents: @agent1 @agent2
+- When you mention an agent, they will be notified and can respond
+- Example: "I think @analyst should review this data" or "Let's ask @researcher to investigate this further"
+
+AVAILABLE AGENTS TO MENTION:
+"""
+
         group_context = (
             f"\n\nYou are part of a group chat named '{self.name}' with the following description: {self.description}\n"
             f"Other participants in this chat:\n"
@@ -163,11 +310,40 @@ class InteractiveGroupChat:
                     for info in agent_info
                     if info["name"] != agent.agent_name
                 ]
-                agent_context = group_context
+                agent_context = group_context + mention_instruction
                 for other in other_agents:
-                    agent_context += (
-                        f"- {other['name']}: {other['description']}\n"
-                    )
+                    agent_context += f"- @{other['name']}: {other['description']}\n"
+
+                # Add final instruction
+                agent_context += """
+                
+COLLABORATION GUIDELINES:
+- ALWAYS read the full conversation history before responding
+- ACKNOWLEDGE other agents' contributions: "Building on @analyst's data insights..." or "I agree with @researcher's findings that..."
+- BUILD UPON previous responses rather than repeating information
+- SYNTHESIZE multiple perspectives when possible
+- ASK CLARIFYING QUESTIONS if you need more information from other agents
+- DELEGATE appropriately: "Let me ask @expert_agent to verify this" or "@specialist, can you elaborate on this point?"
+
+RESPONSE STRUCTURE:
+1. ACKNOWLEDGE: "I've reviewed the responses from @agent1 and @agent2..."
+2. BUILD: "Building on @agent1's analysis of the data..."
+3. CONTRIBUTE: "From my perspective, I would add..."
+4. COLLABORATE: "To get a complete picture, let me ask @agent3 to..."
+5. SYNTHESIZE: "Combining our insights, the key findings are..."
+
+EXAMPLES OF GOOD COLLABORATION:
+- "I've reviewed @analyst's data analysis and @researcher's market insights. The data shows strong growth potential, and I agree with @researcher that we should focus on emerging markets. Let me add that from a content perspective, we should @writer to create targeted messaging for these markets."
+- "Building on @researcher's findings about customer behavior, I can see that @analyst's data supports this trend. To get a complete understanding, let me ask @writer to help us craft messaging that addresses these specific customer needs."
+
+AVOID:
+- Ignoring other agents' responses
+- Repeating what others have already said
+- Making assumptions without consulting relevant experts
+- Responding in isolation without considering the group's collective knowledge
+
+Remember: You are part of a team. Your response should reflect that you've read, understood, and built upon the contributions of others.
+"""
 
                 # Update the agent's system prompt
                 agent.system_prompt = (
@@ -202,6 +378,118 @@ class InteractiveGroupChat:
             logger.error(f"Error extracting mentions: {e}")
             raise InvalidTaskFormatError(f"Invalid task format: {e}")
 
+    def _get_speaking_order(
+        self, mentioned_agents: List[str]
+    ) -> List[str]:
+        """
+        Determines the speaking order using the configured speaker function.
+
+        Args:
+            mentioned_agents: List of agent names that were mentioned
+
+        Returns:
+            List of agent names in the order they should speak
+        """
+        if not mentioned_agents:
+            return []
+
+        # Use the speaker function to determine order
+        try:
+            if self.speaker_function == round_robin_speaker:
+                # For round robin, we need to maintain state
+                current_index = self.speaker_state.get(
+                    "current_index", 0
+                )
+                ordered_agents = []
+
+                # Create the order starting from current index
+                for i in range(len(mentioned_agents)):
+                    agent = round_robin_speaker(
+                        mentioned_agents, current_index + i
+                    )
+                    ordered_agents.append(agent)
+
+                # Update state for next round
+                self.speaker_state["current_index"] = (
+                    current_index + len(mentioned_agents)
+                ) % len(mentioned_agents)
+                return ordered_agents
+
+            elif self.speaker_function == random_speaker:
+                # For random, shuffle the list
+                shuffled = mentioned_agents.copy()
+                random.shuffle(shuffled)
+                return shuffled
+
+            elif self.speaker_function == priority_speaker:
+                # For priority, we need priorities in speaker_state
+                priorities = self.speaker_state.get("priorities", {})
+                if not priorities:
+                    # Fallback to random if no priorities set
+                    shuffled = mentioned_agents.copy()
+                    random.shuffle(shuffled)
+                    return shuffled
+
+                # Sort by priority (higher priority first)
+                sorted_agents = sorted(
+                    mentioned_agents,
+                    key=lambda x: priorities.get(x, 0),
+                    reverse=True,
+                )
+                return sorted_agents
+
+            else:
+                # Custom speaker function
+                # For custom functions, we'll use the first agent returned
+                # and then process the rest in original order
+                first_speaker = self.speaker_function(
+                    mentioned_agents, **self.speaker_state
+                )
+                if first_speaker in mentioned_agents:
+                    remaining = [
+                        agent
+                        for agent in mentioned_agents
+                        if agent != first_speaker
+                    ]
+                    return [first_speaker] + remaining
+                else:
+                    return mentioned_agents
+
+        except Exception as e:
+            logger.error(f"Error in speaker function: {e}")
+            # Fallback to original order
+            return mentioned_agents
+
+    def set_speaker_function(
+        self,
+        speaker_function: Callable,
+        speaker_state: Optional[dict] = None,
+    ) -> None:
+        """
+        Set a custom speaker function and optional state.
+
+        Args:
+            speaker_function: Function that determines speaking order
+            speaker_state: Optional state for the speaker function
+        """
+        self.speaker_function = speaker_function
+        if speaker_state:
+            self.speaker_state.update(speaker_state)
+        self._validate_speaker_function()
+        logger.info(
+            f"Speaker function updated to: {speaker_function.__name__}"
+        )
+
+    def set_priorities(self, priorities: dict) -> None:
+        """
+        Set agent priorities for priority-based speaking order.
+
+        Args:
+            priorities: Dictionary mapping agent names to priority weights
+        """
+        self.speaker_state["priorities"] = priorities
+        logger.info(f"Agent priorities set: {priorities}")
+
     def start_interactive_session(self):
         """
         Start an interactive terminal session for chatting with agents.
@@ -263,9 +551,9 @@ class InteractiveGroupChat:
 
                 # Process the task and get responses
                 try:
-                    response = self.run(user_input)
+                    self.run(user_input)
                     print("\nChat:")
-                    print(response)
+                    # print(response)
 
                 except NoMentionedAgentsError:
                     print(
@@ -303,8 +591,16 @@ class InteractiveGroupChat:
             # Add user task to conversation
             self.conversation.add(role="User", content=task)
 
-            # Get responses from mentioned agents
-            for agent_name in mentioned_agents:
+            # Determine speaking order using speaker function
+            speaking_order = self._get_speaking_order(
+                mentioned_agents
+            )
+            logger.info(
+                f"Speaking order determined: {speaking_order}"
+            )
+
+            # Get responses from mentioned agents in the determined order
+            for agent_name in speaking_order:
                 agent = self.agent_map.get(agent_name)
                 if not agent:
                     raise AgentNotFoundError(
@@ -319,9 +615,20 @@ class InteractiveGroupChat:
 
                     # Get response from agent
                     if isinstance(agent, Agent):
-                        response = agent.run(
-                            task=f"{context}\nPlease respond to the latest task as {agent_name}."
-                        )
+                        collaborative_task = f"""{context}
+
+COLLABORATIVE TASK: Please respond to the latest task as {agent_name}.
+
+IMPORTANT INSTRUCTIONS:
+1. Read the ENTIRE conversation history above
+2. Acknowledge what other agents have said before adding your perspective
+3. Build upon their insights rather than repeating information
+4. If you need input from other agents, mention them using @agent_name
+5. Provide your unique expertise while showing you understand the group's collective knowledge
+
+Remember: You are part of a collaborative team. Your response should demonstrate that you've read, understood, and are building upon the contributions of others."""
+
+                        response = agent.run(task=collaborative_task)
                     else:
                         # For callable functions
                         response = agent(context)

swarms/structs/ma_utils.py

@@ -1,12 +1,17 @@
 from typing import List, Any, Optional, Union, Callable
 import random
+from swarms.prompts.collaborative_prompts import (
+    get_multi_agent_collaboration_prompt_one,
+)
 
 
 def list_all_agents(
     agents: List[Union[Callable, Any]],
     conversation: Optional[Any] = None,
-    name: str = "",
-    add_to_conversation: bool = False,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    add_to_conversation: Optional[bool] = False,
+    add_collaboration_prompt: Optional[bool] = True,
 ) -> str:
     """Lists all agents in a swarm and optionally adds them to a conversation.
 
@@ -27,6 +32,7 @@ def list_all_agents(
         >>> conversation = Conversation()
         >>> agent_info = list_all_agents(agents, conversation, "MySwarm")
         >>> print(agent_info)
+        Swarm: MySwarm
         Total Agents: 2
 
         Agent: Agent1
@@ -39,8 +45,15 @@ def list_all_agents(
     # Compile information about all agents
     total_agents = len(agents)
 
-    all_agents = f"Total Agents: {total_agents}\n\n" + "\n\n".join(
-        f"Agent: {agent.agent_name} \n\n Description: {agent.description or (agent.system_prompt[:50] + '...' if len(agent.system_prompt) > 50 else agent.system_prompt)}"
+    all_agents = f"Team Name: {name}\n" if name else ""
+    all_agents += (
+        f"Team Description: {description}\n" if description else ""
+    )
+    all_agents += f"Total Agents: {total_agents}\n\n"
+    all_agents += "| Agent | Description |\n"
+    all_agents += "|-------|-------------|\n"
+    all_agents += "\n".join(
+        f"| {agent.agent_name} | {agent.description or (agent.system_prompt[:50] + '...' if len(agent.system_prompt) > 50 else agent.system_prompt)} |"
         for agent in agents
     )
 
@@ -48,10 +61,15 @@ def list_all_agents(
         # Add the agent information to the conversation
         conversation.add(
             role="System",
-            content=f"All Agents Available in the Swarm {name}:\n\n{all_agents}",
+            content=all_agents,
         )
 
-    return all_agents
+    if add_collaboration_prompt:
+        return get_multi_agent_collaboration_prompt_one(
+            agents_in_swarm=all_agents
+        )
+    else:
+        return all_agents
 
 
 models = [
@@ -68,6 +86,7 @@ models = [
     "o4-mini",
     "o3",
     "gpt-4.1",
+    "groq/llama-3.1-8b-instant",
     "gpt-4.1-nano",
 ]