swarms 7.9.6__py3-none-any.whl → 7.9.8__py3-none-any.whl

swarms/agents/reasoning_agents.py

@@ -1,3 +1,41 @@
+"""
+ReasoningAgentRouter: A flexible router for advanced reasoning agent swarms.
+
+This module provides the ReasoningAgentRouter class, which enables dynamic selection and instantiation
+of various advanced reasoning agent types (swarms) for complex problem-solving tasks. It supports
+multiple reasoning strategies, including self-consistency, collaborative duo agents, iterative
+reflection, knowledge prompting, and agent judging.
+
+Key Features:
+- Unified interface for multiple agent types (see `agent_types`)
+- Caching of agent instances for efficiency and memory management
+- Extensible factory-based architecture for easy addition of new agent types
+- Batch and single-task execution
+- Customizable agent configuration (model, prompt, memory, etc.)
+
+Supported Agent Types:
+    - "reasoning-duo" / "reasoning-agent": Dual collaborative agent system
+    - "self-consistency" / "consistency-agent": Multiple independent solutions with consensus
+    - "ire" / "ire-agent": Iterative Reflective Expansion agent
+    - "ReflexionAgent": Reflexion agent with memory
+    - "GKPAgent": Generated Knowledge Prompting agent
+    - "AgentJudge": Agent judge for evaluation/critique
+
+Example usage:
+    >>> router = ReasoningAgentRouter(swarm_type="self-consistency", num_samples=3)
+    >>> result = router.run("What is the capital of France?")
+    >>> print(result)
+
+    >>> # Batch mode
+    >>> results = router.batched_run(["2+2?", "3+3?"])
+    >>> print(results)
+
+See also:
+    - docs/swarms/agents/reasoning_agent_router.md for detailed documentation and architecture diagrams.
+    - consistency_example.py for a usage example with SelfConsistencyAgent.
+
+"""
+
 from typing import (
     List,
     Literal,
@@ -6,9 +44,9 @@ from typing import (
     Any,
     Tuple,
     Hashable,
+    Optional,
 )
 
-
 from swarms.agents.consistency_agent import SelfConsistencyAgent
 from swarms.agents.flexion_agent import ReflexionAgent
 from swarms.agents.gkp_agent import GKPAgent
@@ -19,7 +57,7 @@ from swarms.agents.reasoning_duo import ReasoningDuo
 from swarms.utils.output_types import OutputType
 from swarms.agents.agent_judge import AgentJudge
 
-
+#: Supported agent type literals for ReasoningAgentRouter
 agent_types = Literal[
     "reasoning-duo",
     "self-consistency",
@@ -35,18 +73,30 @@ agent_types = Literal[
 
 class ReasoningAgentRouter:
     """
-    A Reasoning Agent that can answer questions and assist with various tasks using different reasoning strategies.
-
-
-    Attributes:
-        agent_name (str): The name of the agent.
-        description (str): A brief description of the agent's capabilities.
-        model_name (str): The name of the model used for reasoning.
-        system_prompt (str): The prompt that guides the agent's reasoning process.
-        max_loops (int): The maximum number of loops for the reasoning process.
-        swarm_type (agent_types): The type of reasoning swarm to use (e.g., reasoning duo, self-consistency, IRE).
-        num_samples (int): The number of samples to generate for self-consistency agents.
-        output_type (OutputType): The format of the output (e.g., dict, list).
+    A router for advanced reasoning agent swarms.
+
+    The ReasoningAgentRouter enables dynamic selection, instantiation, and caching of various
+    reasoning agent types ("swarms") for flexible, robust, and scalable problem-solving.
+
+    Args:
+        agent_name (str): Name identifier for the agent instance.
+        description (str): Description of the agent's capabilities.
+        model_name (str): The underlying language model to use.
+        system_prompt (str): System prompt for the agent.
+        max_loops (int): Maximum number of reasoning loops.
+        swarm_type (agent_types): Type of reasoning swarm to use.
+        num_samples (int): Number of samples for self-consistency or iterations.
+        output_type (OutputType): Format of the output.
+        num_knowledge_items (int): Number of knowledge items for GKP agent.
+        memory_capacity (int): Memory capacity for agents that support it.
+        eval (bool): Enable evaluation mode for self-consistency.
+        random_models_on (bool): Enable random model selection for diversity.
+        majority_voting_prompt (Optional[str]): Custom prompt for majority voting.
+
+    Example:
+        >>> router = ReasoningAgentRouter(swarm_type="reasoning-duo")
+        >>> result = router.run("Explain quantum entanglement.")
+        >>> print(result)
     """
 
     # Class variable to store cached agent instances
@@ -59,12 +109,20 @@ class ReasoningAgentRouter:
         model_name: str = "gpt-4o-mini",
         system_prompt: str = "You are a helpful assistant that can answer questions and help with tasks.",
         max_loops: int = 1,
-        swarm_type: agent_types = "reasoning_duo",
+        swarm_type: agent_types = "reasoning-duo",
         num_samples: int = 1,
-        output_type: OutputType = "dict",
+        output_type: OutputType = "dict-all-except-first",
         num_knowledge_items: int = 6,
         memory_capacity: int = 6,
+        eval: bool = False,
+        random_models_on: bool = False,
+        majority_voting_prompt: Optional[str] = None,
     ):
+        """
+        Initialize the ReasoningAgentRouter with the specified configuration.
+
+        See class docstring for parameter details.
+        """
         self.agent_name = agent_name
         self.description = description
         self.model_name = model_name
@@ -75,14 +133,17 @@ class ReasoningAgentRouter:
         self.output_type = output_type
         self.num_knowledge_items = num_knowledge_items
         self.memory_capacity = memory_capacity
+        self.eval = eval
+        self.random_models_on = random_models_on
+        self.majority_voting_prompt = majority_voting_prompt
 
-        # Added: Initialize the factory mapping dictionary
-
+        # Initialize the factory mapping dictionary
         self._initialize_agent_factories()
 
     def _initialize_agent_factories(self) -> None:
         """
         Initialize the agent factory mapping dictionary, mapping various agent types to their respective creation functions.
+
         This method replaces the original if-elif chain, making the code more maintainable and extensible.
         """
         self.agent_factories: Dict[str, Callable[[], Any]] = {
@@ -104,11 +165,11 @@ class ReasoningAgentRouter:
     def _get_cache_key(self) -> Tuple[Hashable, ...]:
         """
         Generate a unique key for cache lookup.
-        The key is based on all relevant configuration parameters of the agent.
 
+        The key is based on all relevant configuration parameters of the agent.
 
         Returns:
-            Tuple[Hashable, ...]: A hashable tuple to serve as the cache key
+            Tuple[Hashable, ...]: A hashable tuple to serve as the cache key.
         """
         return (
             self.swarm_type,
@@ -121,10 +182,18 @@ class ReasoningAgentRouter:
             self.output_type,
             self.num_knowledge_items,
             self.memory_capacity,
+            self.eval,
+            self.random_models_on,
+            self.majority_voting_prompt,
         )
 
     def _create_reasoning_duo(self):
-        """Create an agent instance for the ReasoningDuo type"""
+        """
+        Create an agent instance for the ReasoningDuo type.
+
+        Returns:
+            ReasoningDuo: An instance of the ReasoningDuo agent.
+        """
         return ReasoningDuo(
             agent_name=self.agent_name,
             agent_description=self.description,
@@ -134,19 +203,32 @@ class ReasoningAgentRouter:
         )
 
     def _create_consistency_agent(self):
-        """Create an agent instance for the SelfConsistencyAgent type"""
+        """
+        Create an agent instance for the SelfConsistencyAgent type.
+
+        Returns:
+            SelfConsistencyAgent: An instance of the SelfConsistencyAgent.
+        """
         return SelfConsistencyAgent(
-            agent_name=self.agent_name,
+            name=self.agent_name,
             description=self.description,
             model_name=self.model_name,
             system_prompt=self.system_prompt,
             max_loops=self.max_loops,
             num_samples=self.num_samples,
             output_type=self.output_type,
+            eval=self.eval,
+            random_models_on=self.random_models_on,
+            majority_voting_prompt=self.majority_voting_prompt,
         )
 
     def _create_ire_agent(self):
-        """Create an agent instance for the IREAgent type"""
+        """
+        Create an agent instance for the IREAgent type.
+
+        Returns:
+            IREAgent: An instance of the IterativeReflectiveExpansion agent.
+        """
         return IREAgent(
             agent_name=self.agent_name,
             description=self.description,
@@ -158,7 +240,12 @@ class ReasoningAgentRouter:
         )
 
     def _create_agent_judge(self):
-        """Create an agent instance for the AgentJudge type"""
+        """
+        Create an agent instance for the AgentJudge type.
+
+        Returns:
+            AgentJudge: An instance of the AgentJudge agent.
+        """
         return AgentJudge(
             agent_name=self.agent_name,
             model_name=self.model_name,
@@ -167,16 +254,27 @@ class ReasoningAgentRouter:
         )
 
     def _create_reflexion_agent(self):
-        """Create an agent instance for the ReflexionAgent type"""
+        """
+        Create an agent instance for the ReflexionAgent type.
+
+        Returns:
+            ReflexionAgent: An instance of the ReflexionAgent.
+        """
         return ReflexionAgent(
             agent_name=self.agent_name,
             system_prompt=self.system_prompt,
             model_name=self.model_name,
             max_loops=self.max_loops,
+            memory_capacity=self.memory_capacity,
         )
 
     def _create_gkp_agent(self):
-        """Create an agent instance for the GKPAgent type"""
+        """
+        Create an agent instance for the GKPAgent type.
+
+        Returns:
+            GKPAgent: An instance of the GKPAgent.
+        """
         return GKPAgent(
             agent_name=self.agent_name,
             model_name=self.model_name,
@@ -186,13 +284,15 @@ class ReasoningAgentRouter:
     def select_swarm(self):
         """
         Select and initialize the appropriate reasoning swarm based on the specified swarm type.
-        Uses a caching mechanism to return a cached instance if an agent with the same configuration already exists.
 
+        Uses a caching mechanism to return a cached instance if an agent with the same configuration already exists.
 
         Returns:
             The selected reasoning swarm instance.
-        """
 
+        Raises:
+            ValueError: If the specified swarm type is invalid.
+        """
         # Generate cache key
         cache_key = self._get_cache_key()
 
@@ -216,25 +316,25 @@ class ReasoningAgentRouter:
         """
         Execute the reasoning process of the selected swarm on a given task.
 
-
         Args:
             task (str): The task or question to be processed by the reasoning agent.
-
+            *args: Additional positional arguments for the agent's run method.
+            **kwargs: Additional keyword arguments for the agent's run method.
 
         Returns:
-            The result of the reasoning process.
+            The result of the reasoning process (format depends on agent and output_type).
         """
         swarm = self.select_swarm()
-        return swarm.run(task=task)
+        return swarm.run(task=task, *args, **kwargs)
 
     def batched_run(self, tasks: List[str], *args, **kwargs):
         """
         Execute the reasoning process on a batch of tasks.
 
-
         Args:
             tasks (List[str]): The list of tasks to process.
-
+            *args: Additional positional arguments for the agent's run method.
+            **kwargs: Additional keyword arguments for the agent's run method.
 
         Returns:
             A list of reasoning process results for each task.
@@ -248,6 +348,7 @@ class ReasoningAgentRouter:
     def clear_cache(cls):
         """
         Clear the agent instance cache.
+
         Use this when you need to free memory or force the creation of new instances.
         """
         cls._agent_cache.clear()

swarms/prompts/collaborative_prompts.py

@@ -1,8 +1,94 @@
-def get_multi_agent_collaboration_prompt_one(agents_in_swarm: str):
+MULTI_AGENT_COLLABORATION_PROMPT_TWO = """
+# Compact Multi-Agent Collaboration Prompt
+
+## Core Directives
+
+You are an AI agent in a multi-agent system. Follow these essential collaboration protocols:
+
+### Role & Boundaries
+- **Stay in your designated role** - never assume another agent's responsibilities
+- When tasks fall outside your scope, redirect to the appropriate agent
+- Respect hierarchy and authority structures
+
+### Communication Requirements
+- **Always ask for clarification** when anything is unclear or incomplete
+- **Share all relevant information** - never withhold details that could impact others
+- **Acknowledge other agents' inputs** explicitly before proceeding
+- Use clear, structured communication
+
+### Task Execution
+- **Confirm task requirements** before starting - restate your understanding
+- **Adhere strictly to specifications** - flag conflicts or impossibilities
+- **Maintain conversation context** - reference previous exchanges when relevant
+- **Verify your work thoroughly** before declaring completion
+
+### Collaboration Protocol
+1. **State Check**: Confirm current context and your role
+2. **Clarify**: Ask specific questions about unclear elements  
+3. **Coordinate**: Align actions with other agents to avoid conflicts
+4. **Verify**: Check outputs meet requirements and constraints
+5. **Communicate**: Clearly report status and next steps
+
+### Termination Criteria
+Only mark tasks complete when:
+- All requirements verified as met
+- Quality checks passed
+- Other agents confirm their portions (if applicable)
+- Clear completion communication provided
+
+### Failure Prevention
+Actively watch for and prevent:
+- Role boundary violations
+- Information withholding
+- Premature task termination
+- Inadequate verification
+- Task objective drift
+
+**Remember**: Success requires reliable collaboration, not just individual performance.
+"""
+
+MULTI_AGENT_COLLABORATION_PROMPT_SHORT = """
+# Multi-Agent Collaboration Rules 
+
+You're collaborating with other agents in a multi-agent system. Follow these rules to ensure smooth and efficient collaboration:
+
+## Core Principles
+- **Stay in your role** - never assume another agent's responsibilities
+- **Ask for clarification** when anything is unclear
+- **Share all relevant information** - never withhold critical details
+- **Verify thoroughly** before declaring completion
+
+## Switch Gate Protocol
+**Before proceeding with any task, confirm:**
+1. Do I understand the exact requirements and constraints?
+2. Is this task within my designated role and scope?
+3. Do I have all necessary information and context?
+4. Have I coordinated with other agents if this affects their work?
+5. Am I ready to execute with full accountability for the outcome?
+
+**If any answer is "no" - STOP and seek clarification before proceeding.**
+
+## Execution Protocol
+1. **Confirm understanding** of task and role
+2. **Coordinate** with other agents to avoid conflicts
+3. **Execute** while maintaining clear communication
+4. **Verify** all requirements are met
+5. **Report** completion with clear status
+
+## Termination Criteria
+Only complete when all requirements verified, quality checks passed, and completion clearly communicated.
+
+**Remember**: Collective success through reliable collaboration, not just individual performance.
+"""
+
+
+def get_multi_agent_collaboration_prompt_one(
+    agents: str, short_version: bool = False
+):
     MULTI_AGENT_COLLABORATION_PROMPT_ONE = f"""
     You are all operating within a multi-agent collaborative system. Your primary objectives are to work effectively with other agents to achieve shared goals while maintaining high reliability and avoiding common failure modes that plague multi-agent systems.
     
-    {agents_in_swarm}
+    {agents}
 
     ## Fundamental Collaboration Principles
 
@@ -124,54 +210,7 @@ def get_multi_agent_collaboration_prompt_one(agents_in_swarm: str):
     Remember: The goal is not just individual success, but collective success through reliable, high-quality collaboration that builds trust and produces superior outcomes.
     """
 
-    return MULTI_AGENT_COLLABORATION_PROMPT_ONE
-
-
-MULTI_AGENT_COLLABORATION_PROMPT_TWO = """
-# Compact Multi-Agent Collaboration Prompt
-
-## Core Directives
-
-You are an AI agent in a multi-agent system. Follow these essential collaboration protocols:
-
-### Role & Boundaries
-- **Stay in your designated role** - never assume another agent's responsibilities
-- When tasks fall outside your scope, redirect to the appropriate agent
-- Respect hierarchy and authority structures
-
-### Communication Requirements
-- **Always ask for clarification** when anything is unclear or incomplete
-- **Share all relevant information** - never withhold details that could impact others
-- **Acknowledge other agents' inputs** explicitly before proceeding
-- Use clear, structured communication
-
-### Task Execution
-- **Confirm task requirements** before starting - restate your understanding
-- **Adhere strictly to specifications** - flag conflicts or impossibilities
-- **Maintain conversation context** - reference previous exchanges when relevant
-- **Verify your work thoroughly** before declaring completion
-
-### Collaboration Protocol
-1. **State Check**: Confirm current context and your role
-2. **Clarify**: Ask specific questions about unclear elements  
-3. **Coordinate**: Align actions with other agents to avoid conflicts
-4. **Verify**: Check outputs meet requirements and constraints
-5. **Communicate**: Clearly report status and next steps
-
-### Termination Criteria
-Only mark tasks complete when:
-- All requirements verified as met
-- Quality checks passed
-- Other agents confirm their portions (if applicable)
-- Clear completion communication provided
-
-### Failure Prevention
-Actively watch for and prevent:
-- Role boundary violations
-- Information withholding
-- Premature task termination
-- Inadequate verification
-- Task objective drift
-
-**Remember**: Success requires reliable collaboration, not just individual performance.
-"""
+    if short_version:
+        return MULTI_AGENT_COLLABORATION_PROMPT_SHORT
+    else:
+        return MULTI_AGENT_COLLABORATION_PROMPT_ONE

swarms/prompts/hiearchical_system_prompt.py

@@ -0,0 +1,159 @@
+HIEARCHICAL_SWARM_SYSTEM_PROMPT = """
+
+**SYSTEM PROMPT: HIERARCHICAL AGENT DIRECTOR**
+
+**I. Introduction and Context**
+
+You are a 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.
+
+"""

swarms/structs/__init__.py

@@ -91,6 +91,8 @@ from swarms.structs.interactive_groupchat import (
     random_dynamic_speaker,
 )
 
+from swarms.structs.hiearchical_swarm import HierarchicalSwarm
+
 __all__ = [
     "Agent",
     "BaseStructure",
@@ -166,4 +168,5 @@ __all__ = [
     "random_speaker",
     "priority_speaker",
     "random_dynamic_speaker",
+    "HierarchicalSwarm",
 ]