swarms 7.9.9__py3-none-any.whl → 8.0.0__py3-none-any.whl

swarms/structs/qa_swarm.py

@@ -0,0 +1,253 @@
+from swarms.structs.agent import Agent
+from typing import List
+from swarms.structs.conversation import Conversation
+import uuid
+import random
+from loguru import logger
+from typing import Optional
+
+
+class QASwarm:
+    """
+    A Question and Answer swarm system where random agents ask questions to speaker agents.
+
+    This system allows for dynamic Q&A sessions where:
+    - Multiple agents can act as questioners
+    - One or multiple agents can act as speakers/responders
+    - Questions are asked randomly by different agents
+    - The conversation is tracked and managed
+    - Agents are showcased to each other with detailed information
+    """
+
+    def __init__(
+        self,
+        name: str = "QandA",
+        description: str = "Question and Answer Swarm System",
+        agents: List[Agent] = None,
+        speaker_agents: List[Agent] = None,
+        id: str = str(uuid.uuid4()),
+        max_loops: int = 5,
+        show_dashboard: bool = True,
+        speaker_agent: Agent = None,
+        showcase_agents: bool = True,
+        **kwargs,
+    ):
+        self.id = id
+        self.name = name
+        self.description = description
+        self.max_loops = max_loops
+        self.show_dashboard = show_dashboard
+        self.agents = agents or []
+        self.speaker_agents = speaker_agents or []
+        self.kwargs = kwargs
+        self.speaker_agent = speaker_agent
+        self.showcase_agents = showcase_agents
+
+        self.conversation = Conversation()
+
+        # Validate setup
+        self._validate_setup()
+
+    def _validate_setup(self):
+        """Validate that the Q&A system is properly configured."""
+        if not self.agents:
+            logger.warning(
+                "No questioner agents provided. Add agents using add_agent() method."
+            )
+
+        if not self.speaker_agents and not self.speaker_agent:
+            logger.warning(
+                "No speaker agents provided. Add speaker agents using add_speaker_agent() method."
+            )
+
+        if (
+            not self.agents
+            and not self.speaker_agents
+            and not self.speaker_agent
+        ):
+            raise ValueError(
+                "At least one agent (questioner or speaker) must be provided."
+            )
+
+    def add_agent(self, agent: Agent):
+        """Add a questioner agent to the swarm."""
+        self.agents.append(agent)
+        logger.info(f"Added questioner agent: {agent.agent_name}")
+
+    def add_speaker_agent(self, agent: Agent):
+        """Add a speaker agent to the swarm."""
+        if self.speaker_agents is None:
+            self.speaker_agents = []
+        self.speaker_agents.append(agent)
+        logger.info(f"Added speaker agent: {agent.agent_name}")
+
+    def get_agent_info(self, agent: Agent) -> dict:
+        """Extract key information about an agent for showcasing."""
+        info = {
+            "name": getattr(agent, "agent_name", "Unknown Agent"),
+            "description": getattr(
+                agent, "agent_description", "No description available"
+            ),
+            "role": getattr(agent, "role", "worker"),
+        }
+
+        # Get system prompt preview (first 50 characters)
+        system_prompt = getattr(agent, "system_prompt", "")
+        if system_prompt:
+            info["system_prompt_preview"] = (
+                system_prompt[:50] + "..."
+                if len(system_prompt) > 50
+                else system_prompt
+            )
+        else:
+            info["system_prompt_preview"] = (
+                "No system prompt available"
+            )
+
+        return info
+
+    def showcase_speaker_to_questioner(
+        self, questioner: Agent, speaker: Agent
+    ) -> str:
+        """Create a showcase prompt introducing the speaker agent to the questioner."""
+        speaker_info = self.get_agent_info(speaker)
+
+        showcase_prompt = f"""
+        You are about to ask a question to a specialized agent. Here's what you need to know about them:
+
+        **Speaker Agent Information:**
+        - **Name**: {speaker_info['name']}
+        - **Role**: {speaker_info['role']}
+        - **Description**: {speaker_info['description']}
+        - **System Prompt Preview**: {speaker_info['system_prompt_preview']}
+
+        Please craft a thoughtful, relevant question that takes into account this agent's expertise and background. 
+        Your question should be specific and demonstrate that you understand their role and capabilities.
+        """
+        return showcase_prompt
+
+    def showcase_questioner_to_speaker(
+        self, speaker: Agent, questioner: Agent
+    ) -> str:
+        """Create a showcase prompt introducing the questioner agent to the speaker."""
+        questioner_info = self.get_agent_info(questioner)
+
+        showcase_prompt = f"""
+You are about to answer a question from another agent. Here's what you need to know about them:
+
+**Questioner Agent Information:**
+- **Name**: {questioner_info['name']}
+- **Role**: {questioner_info['role']}
+- **Description**: {questioner_info['description']}
+- **System Prompt Preview**: {questioner_info['system_prompt_preview']}
+
+Please provide a comprehensive answer that demonstrates your expertise and addresses their question thoroughly.
+Consider their background and role when formulating your response.
+"""
+        return showcase_prompt
+
+    def random_select_agent(self, agents: List[Agent]) -> Agent:
+        """Randomly select an agent from the list."""
+        if not agents:
+            raise ValueError("No agents available for selection")
+        return random.choice(agents)
+
+    def get_current_speaker(self) -> Agent:
+        """Get the current speaker agent (either from speaker_agents list or single speaker_agent)."""
+        if self.speaker_agent:
+            return self.speaker_agent
+        elif self.speaker_agents:
+            return self.random_select_agent(self.speaker_agents)
+        else:
+            raise ValueError("No speaker agent available")
+
+    def run(
+        self, task: str, img: Optional[str] = None, *args, **kwargs
+    ):
+        """Run the Q&A session with agent showcasing."""
+        self.conversation.add(role="user", content=task)
+
+        # Get current speaker
+        current_speaker = self.get_current_speaker()
+
+        # Select a random questioner
+        questioner = self.random_select_agent(self.agents)
+
+        # Showcase agents to each other if enabled
+        if self.showcase_agents:
+            # Showcase speaker to questioner
+            speaker_showcase = self.showcase_speaker_to_questioner(
+                questioner, current_speaker
+            )
+            questioner_task = f"{speaker_showcase}\n\nNow ask a question about: {task}"
+
+            # Showcase questioner to speaker
+            questioner_showcase = self.showcase_questioner_to_speaker(
+                current_speaker, questioner
+            )
+        else:
+            questioner_task = f"Ask a question about {task} to {current_speaker.agent_name}"
+
+        # Generate question
+        question = questioner.run(
+            task=questioner_task,
+            img=img,
+            *args,
+            **kwargs,
+        )
+
+        self.conversation.add(
+            role=questioner.agent_name, content=question
+        )
+
+        # Prepare answer task with showcasing if enabled
+        if self.showcase_agents:
+            answer_task = f"{questioner_showcase}\n\nAnswer this question from {questioner.agent_name}: {question}"
+        else:
+            answer_task = f"Answer the question '{question}' from {questioner.agent_name}"
+
+        # Generate answer
+        answer = current_speaker.run(
+            task=answer_task,
+            img=img,
+            *args,
+            **kwargs,
+        )
+
+        self.conversation.add(
+            role=current_speaker.agent_name, content=answer
+        )
+
+        return answer
+
+    def run_multi_round(
+        self,
+        task: str,
+        rounds: int = 3,
+        img: Optional[str] = None,
+        *args,
+        **kwargs,
+    ):
+        """Run multiple rounds of Q&A with different questioners."""
+        results = []
+
+        for round_num in range(rounds):
+            logger.info(
+                f"Starting Q&A round {round_num + 1}/{rounds}"
+            )
+
+            round_result = self.run(task, img, *args, **kwargs)
+            results.append(
+                {"round": round_num + 1, "result": round_result}
+            )
+
+        return results
+
+    def get_conversation_history(self):
+        """Get the conversation history."""
+        return self.conversation.get_history()
+
+    def clear_conversation(self):
+        """Clear the conversation history."""
+        self.conversation = Conversation()
+        logger.info("Conversation history cleared")

swarms/structs/swarm_router.py

@@ -28,6 +28,7 @@ from swarms.structs.malt import MALT
 from swarms.structs.deep_research_swarm import DeepResearchSwarm
 from swarms.structs.council_judge import CouncilAsAJudge
 from swarms.structs.interactive_groupchat import InteractiveGroupChat
+from swarms.structs.heavy_swarm import HeavySwarm
 from swarms.structs.ma_utils import list_all_agents
 from swarms.utils.generate_keys import generate_api_key
 
@@ -49,6 +50,7 @@ SwarmType = Literal[
     "DeepResearchSwarm",
     "CouncilAsAJudge",
     "InteractiveGroupChat",
+    "HeavySwarm",
 ]
 
 
@@ -183,6 +185,10 @@ class SwarmRouter:
         conversation: Any = None,
         agents_config: Optional[Dict[Any, Any]] = None,
         speaker_function: str = None,
+        heavy_swarm_loops_per_agent: int = 1,
+        heavy_swarm_question_agent_model_name: str = "gpt-4.1",
+        heavy_swarm_worker_model_name: str = "claude-3-5-sonnet-20240620",
+        telemetry_enabled: bool = False,
         *args,
         **kwargs,
     ):
@@ -210,6 +216,14 @@ class SwarmRouter:
         self.conversation = conversation
         self.agents_config = agents_config
         self.speaker_function = speaker_function
+        self.heavy_swarm_loops_per_agent = heavy_swarm_loops_per_agent
+        self.heavy_swarm_question_agent_model_name = (
+            heavy_swarm_question_agent_model_name
+        )
+        self.heavy_swarm_worker_model_name = (
+            heavy_swarm_worker_model_name
+        )
+        self.telemetry_enabled = telemetry_enabled
 
         # Reliability check
         self.reliability_check()
@@ -234,6 +248,12 @@ class SwarmRouter:
         if self.rules is not None:
             self.handle_rules()
 
+        if self.multi_agent_collab_prompt is True:
+            self.update_system_prompt_for_agent_in_swarm()
+
+        if self.list_all_agents is True:
+            self.list_agents_to_eachother()
+
     def activate_shared_memory(self):
         logger.info("Activating shared memory with all agents ")
 
@@ -283,6 +303,10 @@ class SwarmRouter:
         Handles special case for CouncilAsAJudge which may not require agents.
         """
 
+        logger.info(
+            f"Initializing SwarmRouter: {self.name} Reliability Check..."
+        )
+
         # Check swarm type first since it affects other validations
         if self.swarm_type is None:
             raise ValueError(
@@ -300,6 +324,10 @@ class SwarmRouter:
 
         self.setup()
 
+        logger.info(
+            f"Reliability check for parameters and configurations are complete. SwarmRouter: {self.name} is ready to run!"
+        )
+
     def _create_swarm(self, task: str = None, *args, **kwargs):
         """
         Dynamically create and return the specified swarm type or automatically match the best swarm type for a given task.
@@ -321,6 +349,18 @@ class SwarmRouter:
 
             self._create_swarm(self.swarm_type)
 
+        elif self.swarm_type == "HeavySwarm":
+            return HeavySwarm(
+                name=self.name,
+                description=self.description,
+                agents=self.agents,
+                max_loops=self.max_loops,
+                output_type=self.output_type,
+                loops_per_agent=self.heavy_swarm_loops_per_agent,
+                question_agent_model_name=self.heavy_swarm_question_agent_model_name,
+                worker_model_name=self.heavy_swarm_worker_model_name,
+            )
+
         elif self.swarm_type == "AgentRearrange":
             return AgentRearrange(
                 name=self.name,
@@ -478,6 +518,24 @@ class SwarmRouter:
 
         return agent_config
 
+    def list_agents_to_eachother(self):
+        if self.swarm_type == "SequentialWorkflow":
+            self.conversation = (
+                self.swarm.agent_rearrange.conversation
+            )
+        else:
+            self.conversation = self.swarm.conversation
+
+        if self.list_all_agents is True:
+            list_all_agents(
+                agents=self.agents,
+                conversation=self.swarm.conversation,
+                name=self.name,
+                description=self.description,
+                add_collaboration_prompt=True,
+                add_to_conversation=True,
+            )
+
     def _run(
         self,
         task: str,
@@ -503,31 +561,12 @@ class SwarmRouter:
         """
         self.swarm = self._create_swarm(task, *args, **kwargs)
 
-        if self.swarm_type == "SequentialWorkflow":
-            self.conversation = (
-                self.swarm.agent_rearrange.conversation
-            )
-        else:
-            self.conversation = self.swarm.conversation
-
-        if self.list_all_agents is True:
-            list_all_agents(
-                agents=self.agents,
-                conversation=self.swarm.conversation,
-                name=self.name,
-                description=self.description,
-                add_collaboration_prompt=True,
-                add_to_conversation=True,
-            )
-
-        if self.multi_agent_collab_prompt is True:
-            self.update_system_prompt_for_agent_in_swarm()
-
         log_execution(
             swarm_id=self.id,
             status="start",
             swarm_config=self.to_dict(),
             swarm_architecture="swarm_router",
+            enabled_on=self.telemetry_enabled,
         )
 
         try:
@@ -548,12 +587,13 @@ class SwarmRouter:
                 status="completion",
                 swarm_config=self.to_dict(),
                 swarm_architecture="swarm_router",
+                enabled_on=self.telemetry_enabled,
             )
 
             return result
         except Exception as e:
             raise RuntimeError(
-                f"SwarmRouter: Error executing task on swarm: {str(e)} Traceback: {traceback.format_exc()}"
+                f"SwarmRouter: Error executing task on swarm: {str(e)} Traceback: {traceback.format_exc()}. Try reconfiguring the SwarmRouter Settings and or make sure the individual agents are configured correctly."
             )
 
     def run(

swarms/telemetry/log_executions.py

@@ -1,5 +1,250 @@
 from typing import Optional
 from swarms.telemetry.main import log_agent_data
+import functools
+import inspect
+import time
+from datetime import datetime
+
+
+def log_function_execution(
+    swarm_id: Optional[str] = None,
+    swarm_architecture: Optional[str] = None,
+    enabled_on: Optional[bool] = True,
+):
+    """
+    Decorator to log function execution details including parameters and outputs.
+
+    This decorator automatically captures and logs:
+    - Function name
+    - Function parameters (args and kwargs)
+    - Function output/return value
+    - Execution timestamp
+    - Execution duration
+    - Execution status (success/error)
+
+    Args:
+        swarm_id (str, optional): Unique identifier for the swarm instance
+        swarm_architecture (str, optional): Name of the swarm architecture
+        enabled_on (bool, optional): Whether logging is enabled. Defaults to True.
+
+    Returns:
+        Decorated function that logs execution details
+
+    Example:
+        >>> @log_function_execution(swarm_id="my-swarm", swarm_architecture="sequential")
+        ... def process_data(data, threshold=0.5):
+        ...     return {"processed": len(data), "threshold": threshold}
+        ...
+        >>> result = process_data([1, 2, 3], threshold=0.8)
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if not enabled_on:
+                return func(*args, **kwargs)
+
+            # Capture function details
+            function_name = func.__name__
+            function_module = func.__module__
+            start_time = time.time()
+            timestamp = datetime.now().isoformat()
+
+            # Capture function parameters
+            sig = inspect.signature(func)
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            # Convert parameters to serializable format
+            parameters = {}
+            for (
+                param_name,
+                param_value,
+            ) in bound_args.arguments.items():
+                try:
+                    # Handle special method parameters
+                    if param_name == "self":
+                        # For instance methods, log class name and instance info
+                        parameters[param_name] = {
+                            "class_name": param_value.__class__.__name__,
+                            "class_module": param_value.__class__.__module__,
+                            "instance_id": hex(id(param_value)),
+                            "type": "instance",
+                        }
+                    elif param_name == "cls":
+                        # For class methods, log class information
+                        parameters[param_name] = {
+                            "class_name": param_value.__name__,
+                            "class_module": param_value.__module__,
+                            "type": "class",
+                        }
+                    elif isinstance(
+                        param_value,
+                        (str, int, float, bool, type(None)),
+                    ):
+                        parameters[param_name] = param_value
+                    elif isinstance(param_value, (list, dict, tuple)):
+                        parameters[param_name] = str(param_value)[
+                            :500
+                        ]  # Truncate large objects
+                    elif hasattr(param_value, "__class__"):
+                        # Handle other object instances
+                        parameters[param_name] = {
+                            "class_name": param_value.__class__.__name__,
+                            "class_module": param_value.__class__.__module__,
+                            "instance_id": hex(id(param_value)),
+                            "type": "object_instance",
+                        }
+                    else:
+                        parameters[param_name] = str(
+                            type(param_value)
+                        )
+                except Exception:
+                    parameters[param_name] = "<non-serializable>"
+
+            # Determine if this is a method call and add context
+            method_context = _get_method_context(
+                func, bound_args.arguments
+            )
+
+            execution_data = {
+                "function_name": function_name,
+                "function_module": function_module,
+                "swarm_id": swarm_id,
+                "swarm_architecture": swarm_architecture,
+                "timestamp": timestamp,
+                "parameters": parameters,
+                "status": "start",
+                **method_context,
+            }
+
+            try:
+                # Log function start
+                log_agent_data(data_dict=execution_data)
+
+                # Execute the function
+                result = func(*args, **kwargs)
+
+                # Calculate execution time
+                end_time = time.time()
+                execution_time = end_time - start_time
+
+                # Log successful execution
+                success_data = {
+                    **execution_data,
+                    "status": "success",
+                    "execution_time_seconds": execution_time,
+                    "output": _serialize_output(result),
+                }
+                log_agent_data(data_dict=success_data)
+
+                return result
+
+            except Exception as e:
+                # Calculate execution time even for errors
+                end_time = time.time()
+                execution_time = end_time - start_time
+
+                # Log error execution
+                error_data = {
+                    **execution_data,
+                    "status": "error",
+                    "execution_time_seconds": execution_time,
+                    "error_message": str(e),
+                    "error_type": type(e).__name__,
+                }
+
+                try:
+                    log_agent_data(data_dict=error_data)
+                except Exception:
+                    pass  # Silent fail on logging errors
+
+                # Re-raise the original exception
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def _get_method_context(func, arguments):
+    """
+    Helper function to extract method context information.
+
+    Args:
+        func: The function/method being called
+        arguments: The bound arguments dictionary
+
+    Returns:
+        Dictionary with method context information
+    """
+    context = {}
+
+    try:
+        # Check if this is a method call
+        if "self" in arguments:
+            # Instance method
+            self_obj = arguments["self"]
+            context.update(
+                {
+                    "method_type": "instance_method",
+                    "class_name": self_obj.__class__.__name__,
+                    "class_module": self_obj.__class__.__module__,
+                    "instance_id": hex(id(self_obj)),
+                }
+            )
+        elif "cls" in arguments:
+            # Class method
+            cls_obj = arguments["cls"]
+            context.update(
+                {
+                    "method_type": "class_method",
+                    "class_name": cls_obj.__name__,
+                    "class_module": cls_obj.__module__,
+                }
+            )
+        else:
+            # Regular function or static method
+            context.update({"method_type": "function"})
+
+        # Try to get qualname for additional context
+        if hasattr(func, "__qualname__"):
+            context["qualified_name"] = func.__qualname__
+
+    except Exception:
+        # If anything fails, just mark as unknown
+        context = {"method_type": "unknown"}
+
+    return context
+
+
+def _serialize_output(output):
+    """
+    Helper function to serialize function output for logging.
+
+    Args:
+        output: The function return value to serialize
+
+    Returns:
+        Serializable representation of the output
+    """
+    try:
+        if output is None:
+            return None
+        elif isinstance(output, (str, int, float, bool)):
+            return output
+        elif isinstance(output, (list, dict, tuple)):
+            # Truncate large outputs to prevent log bloat
+            output_str = str(output)
+            return (
+                output_str[:1000] + "..."
+                if len(output_str) > 1000
+                else output_str
+            )
+        else:
+            return str(type(output))
+    except Exception:
+        return "<non-serializable-output>"
 
 
 def log_execution(
@@ -7,6 +252,7 @@ def log_execution(
     status: Optional[str] = None,
     swarm_config: Optional[dict] = None,
     swarm_architecture: Optional[str] = None,
+    enabled_on: Optional[bool] = False,
 ):
     """
     Log execution data for a swarm router instance.
@@ -31,13 +277,16 @@ def log_execution(
         ... )
     """
     try:
-        log_agent_data(
-            data_dict={
-                "swarm_router_id": swarm_id,
-                "status": status,
-                "swarm_router_config": swarm_config,
-                "swarm_architecture": swarm_architecture,
-            }
-        )
+        if enabled_on is None:
+            log_agent_data(
+                data_dict={
+                    "swarm_router_id": swarm_id,
+                    "status": status,
+                    "swarm_router_config": swarm_config,
+                    "swarm_architecture": swarm_architecture,
+                }
+            )
+        else:
+            pass
     except Exception:
         pass