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

swarms/structs/hiearchical_swarm.py

@@ -1,22 +1,33 @@
-import json
-import os
-from typing import Any, List, Optional, Union, Dict
+"""
+Flow:
+
+1. User provides a task
+2. Director creates a plan
+3. Director distributes orders to agents individually or multiple tasks at once
+4. Agents execute tasks and report back to the director
+5. Director evaluates results and issues new orders if needed (up to max_loops)
+6. All context and conversation history is preserved throughout the process
+
+"""
+
+import traceback
+from typing import Any, Callable, List, Literal, Optional, Union
 
 from pydantic import BaseModel, Field
 
+from swarms.prompts.hiearchical_system_prompt import (
+    HIEARCHICAL_SWARM_SYSTEM_PROMPT,
+)
 from swarms.structs.agent import Agent
 from swarms.structs.base_swarm import BaseSwarm
 from swarms.structs.conversation import Conversation
-from swarms.utils.output_types import OutputType
-from swarms.utils.any_to_str import any_to_str
-from swarms.utils.formatter import formatter
-
-from swarms.utils.function_caller_model import OpenAIFunctionCaller
-from swarms.utils.loguru_logger import initialize_logger
+from swarms.structs.ma_utils import list_all_agents
+from swarms.tools.base_tool import BaseTool
 from swarms.utils.history_output_formatter import (
     history_output_formatter,
 )
-from swarms.structs.ma_utils import list_all_agents
+from swarms.utils.loguru_logger import initialize_logger
+from swarms.utils.output_types import OutputType
 
 logger = initialize_logger(log_folder="hierarchical_swarm")
 
@@ -33,204 +44,49 @@ class HierarchicalOrder(BaseModel):
 
 
 class SwarmSpec(BaseModel):
-    goals: str = Field(
-        ...,
-        description="The goal of the swarm. This is the overarching objective that the swarm is designed to achieve. It guides the swarm's plan and the tasks assigned to the agents.",
-    )
     plan: str = Field(
         ...,
         description="Outlines the sequence of actions to be taken by the swarm. This plan is a detailed roadmap that guides the swarm's behavior and decision-making.",
     )
-    rules: str = Field(
-        ...,
-        description="Defines the governing principles for swarm behavior and decision-making. These rules are the foundation of the swarm's operations and ensure that the swarm operates in a coordinated and efficient manner.",
-    )
     orders: List[HierarchicalOrder] = Field(
         ...,
         description="A collection of task assignments to specific agents within the swarm. These orders are the specific instructions that guide the agents in their task execution and are a key element in the swarm's plan.",
     )
 
 
-HIEARCHICAL_SWARM_SYSTEM_PROMPT = """
-
-**SYSTEM PROMPT: HIERARCHICAL AGENT DIRECTOR**
-
-**I. Introduction and Context**
-
-You are the Hierarchical Agent Director – the central orchestrator responsible for breaking down overarching goals into granular tasks and intelligently assigning these tasks to the most suitable worker agents within the swarm. Your objective is to maximize the overall performance of the system by ensuring that every agent is given a task aligned with its strengths, expertise, and available resources.
-
----
-
-**II. Core Operating Principles**
-
-1. **Goal Alignment and Context Awareness:**  
-   - **Overarching Goals:** Begin every operation by clearly reviewing the swarm’s overall goals. Understand the mission statement and ensure that every assigned task contributes directly to these objectives.
-   - **Context Sensitivity:** Evaluate the context provided in the “plan” and “rules” sections of the SwarmSpec. These instructions provide the operational boundaries and behavioral constraints within which you must work.
-
-2. **Task Decomposition and Prioritization:**  
-   - **Hierarchical Decomposition:** Break down the overarching plan into granular tasks. For each major objective, identify subtasks that logically lead toward the goal. This decomposition should be structured in a hierarchical manner, where complex tasks are subdivided into simpler, manageable tasks.
-   - **Task Priority:** Assign a priority level to each task based on urgency, complexity, and impact. Ensure that high-priority tasks receive immediate attention and that resources are allocated accordingly.
-
-3. **Agent Profiling and Matching:**  
-   - **Agent Specialization:** Maintain an up-to-date registry of worker agents, each with defined capabilities, specializations, and performance histories. When assigning tasks, consider the specific strengths of each agent.
-   - **Performance Metrics:** Utilize historical performance metrics and available workload data to select the most suitable agent for each task. If an agent is overburdened or has lower efficiency on a specific type of task, consider alternate agents.
-   - **Dynamic Reassignment:** Allow for real-time reassignments based on the evolving state of the system. If an agent encounters issues or delays, reassign tasks to ensure continuity.
-
-4. **Adherence to Rules and Safety Protocols:**  
-   - **Operational Rules:** Every task must be executed in strict compliance with the “rules” provided in the SwarmSpec. These rules are non-negotiable and serve as the ethical and operational foundation for all decisions.
-   - **Fail-Safe Mechanisms:** Incorporate safety protocols that monitor agent performance and task progress. If an anomaly or failure is detected, trigger a reallocation of tasks or an escalation process to mitigate risks.
-   - **Auditability:** Ensure that every decision and task assignment is logged for auditing purposes. This enables traceability and accountability in system operations.
-
----
-
-**III. Detailed Task Assignment Process**
-
-1. **Input Analysis and Context Setting:**
-   - **Goal Review:** Begin by carefully reading the “goals” string within the SwarmSpec. This is your north star for every decision you make.
-   - **Plan Comprehension:** Analyze the “plan” string for detailed instructions. Identify key milestones, deliverables, and dependencies within the roadmap.
-   - **Rule Enforcement:** Read through the “rules” string to understand the non-negotiable guidelines that govern task assignments. Consider potential edge cases and ensure that your task breakdown respects these boundaries.
-
-2. **Task Breakdown and Subtask Identification:**
-   - **Decompose the Plan:** Using a systematic approach, decompose the overall plan into discrete tasks. For each major phase, identify the specific actions required. Document dependencies among tasks, and note any potential bottlenecks.
-   - **Task Granularity:** Ensure that tasks are broken down to a level of granularity that makes them actionable. Overly broad tasks must be subdivided further until they can be executed by an individual worker agent.
-   - **Inter-Agent Dependencies:** Clearly specify any dependencies that exist between tasks assigned to different agents. This ensures that the workflow remains coherent and that agents collaborate effectively.
-
-3. **Agent Selection Strategy:**
-   - **Capabilities Matching:** For each identified task, analyze the capabilities required. Compare these against the registry of available worker agents. Factor in specialized skills, past performance, current load, and any situational awareness that might influence the assignment.
-   - **Task Suitability:** Consider both the technical requirements of the task and any contextual subtleties noted in the “plan” and “rules.” Ensure that the chosen agent has a proven track record with similar tasks.
-   - **Adaptive Assignments:** Build in flexibility to allow for agent reassignment in real-time. Monitor ongoing tasks and reallocate resources as needed, especially if an agent experiences unexpected delays or issues.
-
-4. **Constructing Hierarchical Orders:**
-   - **Order Creation:** For each task, generate a HierarchicalOrder object that specifies the agent’s name and the task details. The task description should be unambiguous and detailed enough to guide the agent’s execution without requiring additional clarification.
-   - **Order Validation:** Prior to finalizing each order, cross-reference the task requirements against the agent’s profile. Validate that the order adheres to the “rules” of the SwarmSpec and that it fits within the broader operational context.
-   - **Order Prioritization:** Clearly mark high-priority tasks so that agents understand the urgency. In cases where multiple tasks are assigned to a single agent, provide a sequence or ranking to ensure proper execution order.
-
-5. **Feedback and Iteration:**
-   - **Real-Time Monitoring:** Establish feedback loops with worker agents to track the progress of each task. This allows for early detection of issues and facilitates dynamic reassignment if necessary.
-   - **Continuous Improvement:** Regularly review task execution data and agent performance metrics. Use this feedback to refine the task decomposition and agent selection process in future iterations.
-
----
-
-**IV. Execution Guidelines and Best Practices**
-
-1. **Communication Clarity:**
-   - Use clear, concise language in every HierarchicalOrder. Avoid ambiguity by detailing both the “what” and the “how” of the task.
-   - Provide contextual notes when necessary, especially if the task involves dependencies or coordination with other agents.
-
-2. **Documentation and Traceability:**
-   - Record every task assignment in a centralized log. This log should include the agent’s name, task details, time of assignment, and any follow-up actions taken.
-   - Ensure that the entire decision-making process is documented. This aids in post-operation analysis and helps in refining future assignments.
-
-3. **Error Handling and Escalation:**
-   - If an agent is unable to complete a task due to unforeseen challenges, immediately trigger the escalation protocol. Reassign the task to a qualified backup agent while flagging the incident for further review.
-   - Document all deviations from the plan along with the corrective measures taken. This helps in identifying recurring issues and improving the system’s robustness.
-
-4. **Ethical and Operational Compliance:**
-   - Adhere strictly to the rules outlined in the SwarmSpec. Any action that violates these rules is unacceptable, regardless of the potential gains in efficiency.
-   - Maintain transparency in all operations. If a decision or task assignment is questioned, be prepared to justify the choice based on objective criteria such as agent capability, historical performance, and task requirements.
-
-5. **Iterative Refinement:**
-   - After the completion of each mission cycle, perform a thorough debriefing. Analyze the success and shortcomings of the task assignments.
-   - Use these insights to iterate on your hierarchical ordering process. Update agent profiles and adjust your selection strategies based on real-world performance data.
-
----
-
-**V. Exemplary Use Case and Order Breakdown**
-
-Imagine that the swarm’s overarching goal is to perform a comprehensive analysis of market trends for a large-scale enterprise. The “goals” field might read as follows:  
-*“To conduct an in-depth market analysis that identifies emerging trends, competitive intelligence, and actionable insights for strategic decision-making.”*  
-
-The “plan” could outline a multi-phase approach:
-- Phase 1: Data Collection and Preprocessing  
-- Phase 2: Trend Analysis and Pattern Recognition  
-- Phase 3: Report Generation and Presentation of Findings  
-
-The “rules” may specify that all data processing must comply with privacy regulations, and that results must be validated against multiple data sources.  
-
-For Phase 1, the Director breaks down tasks such as “Identify data sources,” “Extract relevant market data,” and “Preprocess raw datasets.” For each task, the director selects agents with expertise in data mining, natural language processing, and data cleaning. A series of HierarchicalOrder objects are created, for example:
-
-1. HierarchicalOrder for Data Collection:
-   - **agent_name:** “DataMiner_Agent”
-   - **task:** “Access external APIs and scrape structured market data from approved financial news sources.”
-
-2. HierarchicalOrder for Data Preprocessing:
-   - **agent_name:** “Preprocess_Expert”
-   - **task:** “Clean and normalize the collected datasets, ensuring removal of duplicate records and compliance with data privacy rules.”
-
-3. HierarchicalOrder for Preliminary Trend Analysis:
-   - **agent_name:** “TrendAnalyst_Pro”
-   - **task:** “Apply statistical models to identify initial trends and anomalies in the market data.”
-
-Each order is meticulously validated against the rules provided in the SwarmSpec and prioritized according to the project timeline. The director ensures that if any of these tasks are delayed, backup agents are identified and the orders are reissued in real time.
-
----
-
-**VI. Detailed Hierarchical Order Construction and Validation**
-
-1. **Order Structuring:**  
-   - Begin by constructing a template that includes placeholders for the agent’s name and a detailed description of the task.  
-   - Ensure that the task description is unambiguous. For instance, rather than stating “analyze data,” specify “analyze the temporal patterns in consumer sentiment from Q1 and Q2, and identify correlations with economic indicators.”
-
-2. **Validation Workflow:**  
-   - Prior to dispatch, each HierarchicalOrder must undergo a validation check. This includes verifying that the agent’s capabilities align with the task, that the task does not conflict with any other orders, and that the task is fully compliant with the operational rules.
-   - If a validation error is detected, the order should be revised. The director may consult with relevant experts or consult historical data to refine the task’s description and ensure it is actionable.
-
-3. **Order Finalization:**  
-   - Once validated, finalize the HierarchicalOrder and insert it into the “orders” list of the SwarmSpec.  
-   - Dispatch the order immediately, ensuring that the worker agent acknowledges receipt and provides an estimated time of completion.  
-   - Continuously monitor the progress, and if any agent’s status changes (e.g., they become overloaded or unresponsive), trigger a reallocation process based on the predefined agent selection strategy.
-
----
-
-**VII. Continuous Monitoring, Feedback, and Dynamic Reassignment**
-
-1. **Real-Time Status Tracking:**  
-   - Use real-time dashboards to monitor each agent’s progress on the assigned tasks.  
-   - Update the hierarchical ordering system dynamically if a task is delayed, incomplete, or requires additional resources.
-
-2. **Feedback Loop Integration:**  
-   - Each worker agent must provide periodic status updates, including intermediate results, encountered issues, and resource usage.
-   - The director uses these updates to adjust task priorities and reassign tasks if necessary. This dynamic feedback loop ensures the overall swarm remains agile and responsive.
-
-3. **Performance Metrics and Analysis:**  
-   - At the conclusion of every mission, aggregate performance metrics and conduct a thorough review of task efficiency.  
-   - Identify any tasks that repeatedly underperform or cause delays, and adjust the agent selection criteria accordingly for future orders.
-   - Document lessons learned and integrate them into the operating procedures for continuous improvement.
-
----
-
-**VIII. Final Directives and Implementation Mandate**
-
-As the Hierarchical Agent Director, your mandate is clear: you must orchestrate the operation with precision, clarity, and unwavering adherence to the overarching goals and rules specified in the SwarmSpec. You are empowered to deconstruct complex objectives into manageable tasks and to assign these tasks to the worker agents best equipped to execute them.
-
-Your decisions must always be data-driven, relying on agent profiles, historical performance, and real-time feedback. Ensure that every HierarchicalOrder is constructed with a clear task description and assigned to an agent whose expertise aligns perfectly with the requirements. Maintain strict compliance with all operational rules, and be ready to adapt dynamically as conditions change.
-
-This production-grade prompt is your operational blueprint. Utilize it to break down orders efficiently, assign tasks intelligently, and steer the swarm toward achieving the defined goals with optimal efficiency and reliability. Every decision you make should reflect a deep commitment to excellence, safety, and operational integrity.
-
-Remember: the success of the swarm depends on your ability to manage complexity, maintain transparency, and dynamically adapt to the evolving operational landscape. Execute your role with diligence, precision, and a relentless focus on performance excellence.
-
-"""
-
-
-class TeamUnit(BaseModel):
-    """Represents a team within a department."""
-
-    name: Optional[str] = Field(
-        None, description="The name of the team."
-    )
-    description: Optional[str] = Field(
-        None, description="A brief description of the team's purpose."
-    )
-    agents: Optional[List[Union[Agent, Any]]] = Field(
-        None,
-        description="A list of agents that are part of the team.",
+SwarmType = Literal[
+    "AgentRearrange",
+    "MixtureOfAgents",
+    "SpreadSheetSwarm",
+    "SequentialWorkflow",
+    "ConcurrentWorkflow",
+    "GroupChat",
+    "MultiAgentRouter",
+    "AutoSwarmBuilder",
+    "HiearchicalSwarm",
+    "auto",
+    "MajorityVoting",
+    "MALT",
+    "DeepResearchSwarm",
+    "CouncilAsAJudge",
+    "InteractiveGroupChat",
+]
+
+
+class SwarmRouterCall(BaseModel):
+    goal: str = Field(
+        ...,
+        description="The goal of the swarm router call. This is the goal that the swarm router will use to determine the best swarm to use.",
     )
-    team_leader: Optional[Union[Agent, Any]] = Field(
-        None, description="The team leader of the team."
+    swarm_type: SwarmType = Field(
+        ...,
+        description="The type of swarm to use. This is the type of swarm that the swarm router will use to determine the best swarm to use.",
     )
 
-    class Config:
-        arbitrary_types_allowed = True
+    task: str = Field(
+        ...,
+        description="The task to be executed by the swarm router. This is the task that the swarm router will use to determine the best swarm to use.",
+    )
 
 
 class HierarchicalSwarm(BaseSwarm):
@@ -248,13 +104,19 @@ class HierarchicalSwarm(BaseSwarm):
         self,
         name: str = "HierarchicalAgentSwarm",
         description: str = "Distributed task swarm",
-        director: Optional[Union[Agent, Any]] = None,
-        agents: List[Union[Agent, Any]] = None,
+        director: Optional[Union[Agent, Callable, Any]] = None,
+        agents: List[Union[Agent, Callable, Any]] = None,
         max_loops: int = 1,
         output_type: OutputType = "dict-all-except-first",
-        director_model_name: str = "gpt-4o",
-        teams: Optional[List[TeamUnit]] = None,
-        inter_agent_loops: int = 1,
+        feedback_director_model_name: str = "gpt-4o-mini",
+        director_name: str = "Director",
+        director_model_name: str = "gpt-4o-mini",
+        verbose: bool = False,
+        add_collaboration_prompt: bool = True,
+        planning_director_agent: Optional[
+            Union[Agent, Callable, Any]
+        ] = None,
+        director_feedback_on: bool = True,
         *args,
         **kwargs,
     ):
@@ -267,441 +129,609 @@ class HierarchicalSwarm(BaseSwarm):
         :param agents: A list of agents within the swarm.
         :param max_loops: The maximum number of feedback loops between the director and agents.
         :param output_type: The format in which to return the output (dict, str, or list).
+        :param verbose: Enable detailed logging with loguru.
         """
         super().__init__(
             name=name,
             description=description,
             agents=agents,
         )
+        self.name = name
         self.director = director
         self.agents = agents
         self.max_loops = max_loops
         self.output_type = output_type
+        self.feedback_director_model_name = (
+            feedback_director_model_name
+        )
+        self.director_name = director_name
+        self.verbose = verbose
         self.director_model_name = director_model_name
-        self.teams = teams
-        self.inter_agent_loops = inter_agent_loops
+        self.add_collaboration_prompt = add_collaboration_prompt
+        self.planning_director_agent = planning_director_agent
+        self.director_feedback_on = director_feedback_on
 
-        self.conversation = Conversation(time_enabled=False)
-        self.current_loop = 0
-        self.agent_outputs = {}  # Store agent outputs for each loop
+        self.init_swarm()
 
-        self.add_name_and_description()
+    def init_swarm(self):
+        """
+        Initializes the swarm.
+        """
+        # Initialize logger only if verbose is enabled
+        if self.verbose:
+            logger.info(
+                f"🚀 Initializing HierarchicalSwarm: {self.name}"
+            )
+            logger.info(
+                f"📊 Configuration - Max loops: {self.max_loops}"
+            )
+
+        self.conversation = Conversation(time_enabled=False)
 
         # Reliability checks
         self.reliability_checks()
 
-        # Handle teams
-        self.handle_teams()
-
-        # List all agents
-        list_all_agents(self.agents, self.conversation, self.name)
-
         self.director = self.setup_director()
 
-    def handle_teams(self):
-        if not self.teams:
-            return
+        self.add_context_to_director()
 
-        # Use list comprehension for faster team processing
-        team_list = [team.model_dump() for team in self.teams]
+        if self.verbose:
+            logger.success(
+                f"✅ HierarchicalSwarm initialized successfully: Name {self.name}"
+            )
 
-        # Use extend() instead of append() in a loop for better performance
-        self.agents.extend(
-            agent for team in team_list for agent in team["agents"]
-        )
+    def add_context_to_director(self):
+        """Add agent context to the director's conversation."""
+        try:
+            if self.verbose:
+                logger.info("📝 Adding agent context to director")
+
+            list_all_agents(
+                agents=self.agents,
+                conversation=self.conversation,
+                add_to_conversation=True,
+                add_collaboration_prompt=self.add_collaboration_prompt,
+            )
 
-        # Add conversation message
-        self.conversation.add(
-            role="System",
-            content=f"Teams Available: {any_to_str(team_list)}",
-        )
+            if self.verbose:
+                logger.success(
+                    "✅ Agent context added to director successfully"
+                )
+
+        except Exception as e:
+            error_msg = (
+                f"❌ Failed to add context to director: {str(e)}"
+            )
+            logger.error(
+                f"{error_msg}\n🔍 Traceback: {traceback.format_exc()}"
+            )
 
     def setup_director(self):
-        director = OpenAIFunctionCaller(
-            model_name=self.director_model_name,
-            system_prompt=HIEARCHICAL_SWARM_SYSTEM_PROMPT,
-            api_key=os.getenv("OPENAI_API_KEY"),
-            temperature=0.5,
-            base_model=SwarmSpec,
-            max_tokens=10000,
-        )
+        """Set up the director agent with proper configuration."""
+        try:
+            if self.verbose:
+                logger.info("🎯 Setting up director agent")
+
+            schema = BaseTool().base_model_to_dict(SwarmSpec)
+
+            if self.verbose:
+                logger.debug(f"📋 Director schema: {schema}")
+
+            # if self.director is not None:
+            #     # if litellm_check_for_tools(self.director.model_name) is True:
+            #     self.director.add_tool_schema([schema])
+
+            #     if self.verbose:
+            #         logger.success(
+            #             "✅ Director agent setup completed successfully"
+            #         )
+
+            #     return self.director
+            # else:
+            return Agent(
+                agent_name=self.director_name,
+                agent_description="A director agent that can create a plan and distribute orders to agents",
+                model_name=self.director_model_name,
+                max_loops=1,
+                base_model=SwarmSpec,
+                tools_list_dictionary=[schema],
+                output_type="dict-all-except-first",
+            )
 
-        return director
+        except Exception as e:
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+            logger.error(error_msg)
 
     def reliability_checks(self):
         """
         Checks if there are any agents and a director set for the swarm.
         Raises ValueError if either condition is not met.
         """
+        try:
+            if self.verbose:
+                logger.info(
+                    f"🔍 Running reliability checks for swarm: {self.name}"
+                )
 
-        logger.info(f"🔍 CHECKING RELIABILITY OF SWARM: {self.name}")
-
-        if len(self.agents) == 0:
-            raise ValueError(
-                "No agents found in the swarm. At least one agent must be provided to create a hierarchical swarm."
-            )
+            if not self.agents or len(self.agents) == 0:
+                raise ValueError(
+                    "No agents found in the swarm. At least one agent must be provided to create a hierarchical swarm."
+                )
 
-        if self.max_loops == 0:
-            raise ValueError(
-                "Max loops must be greater than 0. Please set a valid number of loops."
-            )
+            if self.max_loops <= 0:
+                raise ValueError(
+                    "Max loops must be greater than 0. Please set a valid number of loops."
+                )
 
-        if self.director is None:
-            self.director = self.agents[0]
+            if not self.director:
+                raise ValueError(
+                    "Director not set for the swarm. A director agent is required to coordinate and orchestrate tasks among the agents."
+                )
 
-        if not self.director:
-            raise ValueError(
-                "Director not set for the swarm. A director agent is required to coordinate and orchestrate tasks among the agents."
-            )
+            if self.verbose:
+                logger.success(
+                    f"✅ Reliability checks passed for swarm: {self.name}"
+                )
+                logger.info(
+                    f"📊 Swarm stats - Agents: {len(self.agents)}, Max loops: {self.max_loops}"
+                )
 
-        logger.info(f"🔍 RELIABILITY CHECKS PASSED: {self.name}")
+        except Exception as e:
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+            logger.error(error_msg)
 
     def run_director(
-        self, task: str, loop_context: str = "", img: str = None
+        self,
+        task: str,
+        img: str = None,
     ) -> SwarmSpec:
         """
         Runs a task through the director agent with the current conversation context.
 
         :param task: The task to be executed by the director.
-        :param loop_context: Additional context specific to the current loop.
         :param img: Optional image to be used with the task.
         :return: The SwarmSpec containing the director's orders.
         """
-        # Create a comprehensive context for the director
-        director_context = f"History: {self.conversation.get_str()}"
-
-        if loop_context:
-            director_context += f"\n\nCurrent Loop ({self.current_loop}/{self.max_loops}): {loop_context}"
-
-        director_context += f"\n\nYour Task: {task}"
-
-        # Run the director with the context
-        function_call = self.director.run(task=director_context)
-
-        formatter.print_panel(
-            f"Director Output (Loop {self.current_loop}/{self.max_loops}):\n{function_call}",
-            title="Director's Orders",
-        )
-
-        # Add director's output to the conversation
-        self.conversation.add(
-            role="Director",
-            content=f"Loop {self.current_loop}/{self.max_loops}: {function_call}",
-        )
-
-        return function_call
-
-    def run(
-        self, task: str, img: str = None, *args, **kwargs
-    ) -> Union[str, Dict, List]:
-        """
-        Runs a task through the swarm, involving the director and agents through multiple loops.
-
-        :param task: The task to be executed by the swarm.
-        :param img: Optional image to be used with the task.
-        :return: The output of the swarm's task execution in the specified format.
-        """
-        # Add the initial task to the conversation
-        self.conversation.add(role="User", content=f"Task: {task}")
-
-        # Reset loop counter and agent outputs
-        self.current_loop = 0
-        self.agent_outputs = {}
+        try:
+            if self.verbose:
+                logger.info(
+                    f"🎯 Running director with task: {task[:100]}..."
+                )
 
-        # Initialize loop context
-        loop_context = "Initial planning phase"
+            if self.planning_director_agent is not None:
+                plan = self.planning_director_agent.run(
+                    task=f"History: {self.conversation.get_str()} \n\n Create a detailed step by step comprehensive plan for the director to execute the task: {task}",
+                    img=img,
+                )
 
-        # Execute the loops
-        for loop_idx in range(self.max_loops):
-            self.current_loop = loop_idx + 1
+                task += plan
 
-            # Log loop start
-            logger.info(
-                f"Starting loop {self.current_loop}/{self.max_loops}"
+            # Run the director with the context
+            function_call = self.director.run(
+                task=f"History: {self.conversation.get_str()} \n\n Task: {task}",
+                img=img,
             )
 
-            # Get director's orders
-            swarm_spec = self.run_director(
-                task=task, loop_context=loop_context, img=img
+            self.conversation.add(
+                role="Director", content=function_call
             )
 
-            # Add the swarm specification to the conversation
-            self.add_goal_and_more_in_conversation(swarm_spec)
+            if self.verbose:
+                logger.success("✅ Director execution completed")
+                logger.debug(
+                    f"📋 Director output type: {type(function_call)}"
+                )
 
-            # Parse and execute the orders
-            orders_list = self.parse_swarm_spec(swarm_spec)
+            return function_call
 
-            # Store outputs for this loop
-            self.agent_outputs[self.current_loop] = {}
+        except Exception as e:
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+            logger.error(error_msg)
 
-            # Execute each order
-            for order in orders_list:
-                agent_output = self.run_agent(
-                    agent_name=order.agent_name,
-                    task=order.task,
-                    img=img,
+    def step(self, task: str, img: str = None, *args, **kwargs):
+        """
+        Runs a single step of the hierarchical swarm.
+        """
+        try:
+            if self.verbose:
+                logger.info(
+                    f"👣 Executing single step for task: {task[:100]}..."
                 )
 
-                # Store the agent's output for this loop
-                self.agent_outputs[self.current_loop][
-                    order.agent_name
-                ] = agent_output
-
-            # Prepare context for the next loop
-            loop_context = self.compile_loop_context(
-                self.current_loop
-            )
+            output = self.run_director(task=task, img=img)
 
-            # If this is the last loop, break out
-            if self.current_loop >= self.max_loops:
-                break
+            # Parse the orders
+            plan, orders = self.parse_orders(output)
 
-        # Return the results in the specified format
-        return history_output_formatter(
-            self.conversation, self.output_type
-        )
+            if self.verbose:
+                logger.info(
+                    f"📋 Parsed plan and {len(orders)} orders"
+                )
 
-    def compile_loop_context(self, loop_number: int) -> str:
-        """
-        Compiles the context for a specific loop, including all agent outputs.
+            # Execute the orders
+            outputs = self.execute_orders(orders)
 
-        :param loop_number: The loop number to compile context for.
-        :return: A string representation of the loop context.
-        """
-        if loop_number not in self.agent_outputs:
-            return "No agent outputs available for this loop."
+            if self.verbose:
+                logger.info(f"⚡ Executed {len(outputs)} orders")
 
-        context = f"Results from loop {loop_number}:\n"
+            if self.director_feedback_on is True:
+                feedback = self.feedback_director(outputs)
+            else:
+                feedback = outputs
 
-        for agent_name, output in self.agent_outputs[
-            loop_number
-        ].items():
-            context += f"\n--- {agent_name}'s Output ---\n{output}\n"
+            if self.verbose:
+                logger.success("✅ Step completed successfully")
 
-        return context
+            return feedback
 
-    def add_name_and_description(self):
-        """
-        Adds the swarm's name and description to the conversation.
-        """
-        self.conversation.add(
-            role="System",
-            content=f"\n\nSwarm Name: {self.name}\n\nSwarm Description: {self.description}",
-        )
+        except Exception as e:
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+            logger.error(error_msg)
 
-    def find_agent(self, name: str) -> Optional[Agent]:
+    def run(self, task: str, img: str = None, *args, **kwargs):
         """
-        Finds an agent by its name within the swarm.
+        Executes the hierarchical swarm for a specified number of feedback loops.
 
-        :param name: The name of the agent to find.
-        :return: The agent if found, otherwise None.
-        :raises: ValueError if agent is not found
+        :param task: The initial task to be processed by the swarm.
+        :param img: Optional image input for the agents.
+        :param args: Additional positional arguments.
+        :param kwargs: Additional keyword arguments.
+        :return: The formatted conversation history as output.
         """
         try:
-            # Fast path: use list comprehension for quick lookup
-            matching_agents = [
-                agent
-                for agent in self.agents
-                if agent.agent_name == name
-            ]
-
-            if not matching_agents:
-                error_msg = f"Agent '{name}' not found in the swarm '{self.name}'"
-                logger.error(error_msg)
-                return None
+            current_loop = 0
+            last_output = None
 
-            return matching_agents[0]
+            if self.verbose:
+                logger.info(
+                    f"🚀 Starting hierarchical swarm run: {self.name}"
+                )
+                logger.info(
+                    f"📊 Configuration - Max loops: {self.max_loops}"
+                )
 
-        except Exception as e:
-            logger.error(f"Error finding agent '{name}': {str(e)}")
-            return None
+            while current_loop < self.max_loops:
+                if self.verbose:
+                    logger.info(
+                        f"🔄 Loop {current_loop + 1}/{self.max_loops} - Processing task"
+                    )
+
+                # For the first loop, use the original task.
+                # For subsequent loops, use the feedback from the previous loop as context.
+                if current_loop == 0:
+                    loop_task = task
+                else:
+                    loop_task = (
+                        f"Previous loop results: {last_output}\n\n"
+                        f"Original task: {task}\n\n"
+                        "Based on the previous results and any feedback, continue with the next iteration of the task. "
+                        "Refine, improve, or complete any remaining aspects of the analysis."
+                    )
+
+                # Execute one step of the swarm
+                try:
+                    last_output = self.step(
+                        task=loop_task, img=img, *args, **kwargs
+                    )
+
+                    if self.verbose:
+                        logger.success(
+                            f"✅ Loop {current_loop + 1} completed successfully"
+                        )
+
+                except Exception as e:
+                    error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+                    logger.error(error_msg)
+
+                current_loop += 1
+
+                # Add loop completion marker to conversation
+                self.conversation.add(
+                    role="System",
+                    content=f"--- Loop {current_loop}/{self.max_loops} completed ---",
+                )
 
-    def run_agent(
-        self, agent_name: str, task: str, img: str = None
-    ) -> str:
-        """
-        Runs a task through a specific agent, providing it with the full conversation context.
+            if self.verbose:
+                logger.success(
+                    f"🎉 Hierarchical swarm run completed: {self.name}"
+                )
+                logger.info(
+                    f"📊 Total loops executed: {current_loop}"
+                )
 
-        :param agent_name: The name of the agent to execute the task.
-        :param task: The task to be executed by the agent.
-        :param img: Optional image to be used with the task.
-        :return: The output of the agent's task execution.
-        """
+            return history_output_formatter(
+                conversation=self.conversation, type=self.output_type
+            )
+
+        except Exception as e:
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+            logger.error(error_msg)
+
+    def feedback_director(self, outputs: list):
+        """Provide feedback from the director based on agent outputs."""
         try:
-            agent = self.find_agent(agent_name)
+            if self.verbose:
+                logger.info("📝 Generating director feedback")
 
-            # Prepare context for the agent
-            agent_context = (
-                f"Loop: {self.current_loop}/{self.max_loops}\n"
-                f"History: {self.conversation.get_str()}\n"
-                f"Your Task: {task}"
-            )
+            task = f"History: {self.conversation.get_str()} \n\n"
 
-            # Run the agent with the context
-            formatter.print_panel(
-                f"Running agent '{agent_name}' with task: {task}",
-                title=f"Agent Task - Loop {self.current_loop}/{self.max_loops}",
+            feedback_director = Agent(
+                agent_name="Director",
+                agent_description="Director module that provides feedback to the worker agents",
+                model_name=self.director_model_name,
+                max_loops=1,
+                system_prompt=HIEARCHICAL_SWARM_SYSTEM_PROMPT,
             )
 
-            out = agent.run(task=agent_context)
-
-            # Add the agent's output to the conversation
+            output = feedback_director.run(
+                task=(
+                    "You are the Director. Carefully review the outputs generated by all the worker agents in the previous step. "
+                    "Provide specific, actionable feedback for each agent, highlighting strengths, weaknesses, and concrete suggestions for improvement. "
+                    "If any outputs are unclear, incomplete, or could be enhanced, explain exactly how. "
+                    f"Your feedback should help the agents refine their work in the next iteration. "
+                    f"Worker Agent Responses: {task}"
+                )
+            )
             self.conversation.add(
-                role=agent_name,
-                content=f"Loop {self.current_loop}/{self.max_loops}: {out}",
+                role=self.director.agent_name, content=output
             )
 
-            formatter.print_panel(
-                out,
-                title=f"Output from {agent_name} - Loop {self.current_loop}/{self.max_loops}",
-            )
+            if self.verbose:
+                logger.success(
+                    "✅ Director feedback generated successfully"
+                )
+
+            return output
 
-            return out
         except Exception as e:
-            error_msg = (
-                f"Error running agent '{agent_name}': {str(e)}"
-            )
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
             logger.error(error_msg)
-            return error_msg
 
-    def parse_orders(self, swarm_spec: SwarmSpec) -> List[Any]:
+    def call_single_agent(
+        self, agent_name: str, task: str, *args, **kwargs
+    ):
         """
-        Parses the orders from the SwarmSpec and executes them through the agents.
-
-        :param swarm_spec: The SwarmSpec containing the orders to be parsed.
-        :return: A list of agent outputs.
+        Calls a single agent with the given task.
         """
-        self.add_goal_and_more_in_conversation(swarm_spec)
-        orders_list = self.parse_swarm_spec(swarm_spec)
-        outputs = []
-
         try:
-            for order in orders_list:
-                output = self.run_agent(
-                    agent_name=order.agent_name,
-                    task=order.task,
+            if self.verbose:
+                logger.info(f"📞 Calling agent: {agent_name}")
+
+            # Find agent by name
+            agent = None
+            for a in self.agents:
+                if (
+                    hasattr(a, "agent_name")
+                    and a.agent_name == agent_name
+                ):
+                    agent = a
+                    break
+
+            if agent is None:
+                available_agents = [
+                    a.agent_name
+                    for a in self.agents
+                    if hasattr(a, "agent_name")
+                ]
+                raise ValueError(
+                    f"Agent '{agent_name}' not found in swarm. Available agents: {available_agents}"
                 )
-                outputs.append(output)
 
-            return outputs
-        except Exception as e:
-            error_msg = (
-                f"Error parsing and executing orders: {str(e)}"
+            output = agent.run(
+                task=f"History: {self.conversation.get_str()} \n\n Task: {task}",
+                *args,
+                **kwargs,
             )
+            self.conversation.add(role=agent_name, content=output)
+
+            if self.verbose:
+                logger.success(
+                    f"✅ Agent {agent_name} completed task successfully"
+                )
+
+            return output
+
+        except Exception as e:
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
             logger.error(error_msg)
-            return [error_msg]
 
-    def parse_swarm_spec(
-        self, swarm_spec: SwarmSpec
-    ) -> List[HierarchicalOrder]:
+    def parse_orders(self, output):
         """
-        Parses the SwarmSpec to extract the orders.
-
-        :param swarm_spec: The SwarmSpec to be parsed.
-        :return: The list of orders extracted from the SwarmSpec.
+        Parses the orders from the director's output.
         """
         try:
-            return swarm_spec.orders
-        except AttributeError:
-            logger.error(
-                "Invalid SwarmSpec format: missing 'orders' attribute"
-            )
-            return []
+            if self.verbose:
+                logger.info("📋 Parsing director orders")
+                logger.debug(f"📊 Output type: {type(output)}")
+
+            import json
+
+            # Handle different output formats from the director
+            if isinstance(output, list):
+                # If output is a list, look for function call data
+                for item in output:
+                    if isinstance(item, dict):
+                        # Check if it's a conversation format with role/content
+                        if "content" in item and isinstance(
+                            item["content"], list
+                        ):
+                            for content_item in item["content"]:
+                                if (
+                                    isinstance(content_item, dict)
+                                    and "function" in content_item
+                                ):
+                                    function_data = content_item[
+                                        "function"
+                                    ]
+                                    if "arguments" in function_data:
+                                        try:
+                                            args = json.loads(
+                                                function_data[
+                                                    "arguments"
+                                                ]
+                                            )
+                                            if (
+                                                "plan" in args
+                                                and "orders" in args
+                                            ):
+                                                plan = args["plan"]
+                                                orders = [
+                                                    HierarchicalOrder(
+                                                        **order
+                                                    )
+                                                    for order in args[
+                                                        "orders"
+                                                    ]
+                                                ]
+
+                                                if self.verbose:
+                                                    logger.success(
+                                                        f"✅ Successfully parsed plan and {len(orders)} orders"
+                                                    )
+
+                                                return plan, orders
+                                        except (
+                                            json.JSONDecodeError
+                                        ) as json_err:
+                                            if self.verbose:
+                                                logger.warning(
+                                                    f"⚠️ JSON decode error: {json_err}"
+                                                )
+                                            pass
+                        # Check if it's a direct function call format
+                        elif "function" in item:
+                            function_data = item["function"]
+                            if "arguments" in function_data:
+                                try:
+                                    args = json.loads(
+                                        function_data["arguments"]
+                                    )
+                                    if (
+                                        "plan" in args
+                                        and "orders" in args
+                                    ):
+                                        plan = args["plan"]
+                                        orders = [
+                                            HierarchicalOrder(**order)
+                                            for order in args[
+                                                "orders"
+                                            ]
+                                        ]
+
+                                        if self.verbose:
+                                            logger.success(
+                                                f"✅ Successfully parsed plan and {len(orders)} orders"
+                                            )
+
+                                        return plan, orders
+                                except (
+                                    json.JSONDecodeError
+                                ) as json_err:
+                                    if self.verbose:
+                                        logger.warning(
+                                            f"⚠️ JSON decode error: {json_err}"
+                                        )
+                                    pass
+                # If no function call found, raise error
+                raise ValueError(
+                    f"Unable to parse orders from director output: {output}"
+                )
+            elif isinstance(output, dict):
+                # Handle direct dictionary format
+                if "plan" in output and "orders" in output:
+                    plan = output["plan"]
+                    orders = [
+                        HierarchicalOrder(**order)
+                        for order in output["orders"]
+                    ]
+
+                    if self.verbose:
+                        logger.success(
+                            f"✅ Successfully parsed plan and {len(orders)} orders"
+                        )
+
+                    return plan, orders
+                else:
+                    raise ValueError(
+                        f"Missing 'plan' or 'orders' in director output: {output}"
+                    )
+            else:
+                raise ValueError(
+                    f"Unexpected output format from director: {type(output)}"
+                )
+
         except Exception as e:
-            logger.error(f"Error parsing SwarmSpec: {str(e)}")
-            return []
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+            logger.error(error_msg)
 
-    def provide_feedback(
-        self, agent_outputs: Dict[str, str]
-    ) -> Dict[str, str]:
+    def execute_orders(self, orders: list):
         """
-        Provides feedback to agents based on their outputs.
-
-        :param agent_outputs: A dictionary mapping agent names to their outputs.
-        :return: A dictionary of feedback for each agent.
+        Executes the orders from the director's output.
         """
-        feedback = {}
+        try:
+            if self.verbose:
+                logger.info(f"⚡ Executing {len(orders)} orders")
+
+            outputs = []
+            for i, order in enumerate(orders):
+                if self.verbose:
+                    logger.info(
+                        f"📋 Executing order {i+1}/{len(orders)}: {order.agent_name}"
+                    )
+
+                output = self.call_single_agent(
+                    order.agent_name, order.task
+                )
+                outputs.append(output)
 
-        # Compile all agent outputs for the director
-        agent_outputs_str = "\n\n".join(
-            f"--- {agent_name} Output ---\n{output}"
-            for agent_name, output in agent_outputs.items()
-        )
+            if self.verbose:
+                logger.success(
+                    f"✅ All {len(orders)} orders executed successfully"
+                )
 
-        # Have the director provide feedback
-        feedback_task = (
-            f"Review the following agent outputs and provide feedback for each agent.\n\n"
-            f"{agent_outputs_str}"
-        )
+            return outputs
 
-        feedback_spec = self.run_director(task=feedback_task)
-        feedback_orders = self.parse_swarm_spec(feedback_spec)
+        except Exception as e:
+            error_msg = f"❌ Failed to setup director: {str(e)}\n🔍 Traceback: {traceback.format_exc()}\n🐛 If this issue persists, please report it at: https://github.com/kyegomez/swarms/issues"
+            logger.error(error_msg)
 
-        # Process each feedback order
-        for order in feedback_orders:
-            # The agent receiving feedback
-            agent_name = order.agent_name
-            # The feedback content
-            feedback_content = order.task
+    def batched_run(
+        self, tasks: List[str], img: str = None, *args, **kwargs
+    ):
+        """
+        Executes the hierarchical swarm for a list of tasks.
+        """
+        try:
+            if self.verbose:
+                logger.info(
+                    f"🚀 Starting batched hierarchical swarm run: {self.name}"
+                )
+                logger.info(
+                    f"📊 Configuration - Max loops: {self.max_loops}"
+                )
 
-            # Store the feedback
-            feedback[agent_name] = feedback_content
+            # Initialize a list to store the results
+            results = []
 
-            # Add the feedback to the conversation
-            self.conversation.add(
-                role="Director",
-                content=f"Feedback for {agent_name}: {feedback_content}",
-            )
+            # Process each task in parallel
+            for task in tasks:
+                result = self.run(task, img, *args, **kwargs)
+                results.append(result)
 
-        return feedback
+            if self.verbose:
+                logger.success(
+                    f"🎉 Batched hierarchical swarm run completed: {self.name}"
+                )
+                logger.info(f"📊 Total tasks processed: {len(tasks)}")
 
-    def add_goal_and_more_in_conversation(
-        self, swarm_spec: SwarmSpec
-    ) -> None:
-        """
-        Adds the swarm's goals, plan, and rules to the conversation.
+            return results
 
-        :param swarm_spec: The SwarmSpec containing the goals, plan, and rules.
-        """
-        try:
-            # Directly access and format attributes in one line
-            self.conversation.add(
-                role="Director",
-                content=f"Goals:\n{swarm_spec.goals}\n\nPlan:\n{swarm_spec.plan}\n\nRules:\n{swarm_spec.rules}",
-            )
         except Exception as e:
-            logger.error(
-                f"Error adding goals and plan to conversation: {str(e)}"
+            error_msg = (
+                f"❌ Batched hierarchical swarm run failed: {str(e)}"
             )
-
-    def batch_run(
-        self, tasks: List[str], img: str = None
-    ) -> List[Union[str, Dict, List]]:
-        """
-        Runs multiple tasks sequentially through the swarm.
-
-        :param tasks: The list of tasks to be executed.
-        :param img: Optional image to be used with the tasks.
-        :return: A list of outputs from each task execution.
-        """
-        return [self.run(task, img) for task in tasks]
-
-    def check_director_agent_output(self, output: any) -> dict:
-        if isinstance(output, dict):
-            return output
-        elif isinstance(output, str):
-            try:
-                # Attempt to parse the string as JSON
-                return json.loads(output)
-            except json.JSONDecodeError as e:
-                # Log an error if the string cannot be parsed
+            if self.verbose:
+                logger.error(error_msg)
                 logger.error(
-                    f"Failed to parse output string as JSON: {str(e)}"
+                    f"🔍 Traceback: {traceback.format_exc()}"
                 )
-                return {}
-        else:
-            # Log an error if the output is neither a dict nor a string
-            logger.error(
-                "Output is neither a dictionary nor a string."
-            )
-            return {}