[5.6.8]

agents_from_yaml_example.py

@@ -6,15 +6,19 @@
 load_dotenv()
 
 # Path to your YAML file
-yaml_file = 'agents_config.yaml'
+yaml_file = "agents_config.yaml"
 
 try:
     # Create agents and run tasks (using 'both' to return agents and task results)
-    agents, task_results = create_agents_from_yaml(yaml_file, return_type="both")
+    agents, task_results = create_agents_from_yaml(
+        yaml_file, return_type="both"
+    )
 
     # Print the results of the tasks
     for result in task_results:
-        print(f"Agent: {result['agent_name']} | Task: {result['task']} | Output: {result.get('output', 'Error encountered')}")
+        print(
+            f"Agent: {result['agent_name']} | Task: {result['task']} | Output: {result.get('output', 'Error encountered')}"
+        )
 
 except Exception as e:
-    logger.error(f"An error occurred: {e}")
+    logger.error(f"An error occurred: {e}")

docs/mkdocs.yml

@@ -166,6 +166,7 @@ nav:
         - GroupChat: "swarms/structs/group_chat.md"
         - AgentRegistry: "swarms/structs/agent_registry.md"
         - SpreadSheetSwarm: "swarms/structs/spreadsheet_swarm.md"
+        - ForestSwarm: "swarms/structs/forest_swarm.md"
         - Workflows:
             - ConcurrentWorkflow: "swarms/structs/concurrentworkflow.md"
             - SequentialWorkflow: "swarms/structs/sequential_workflow.md"

docs/swarms/structs/forest_swarm.md

@@ -0,0 +1,141 @@
+# Forest Swarm
+
+This documentation describes the **ForestSwarm** that organizes agents into trees. Each agent specializes in processing specific tasks. Trees are collections of agents, each assigned based on their relevance to a task through keyword extraction and embedding-based similarity.
+
+The architecture allows for efficient task assignment by selecting the most relevant agent from a set of trees. Tasks are processed asynchronously, with agents selected based on task relevance, calculated by the similarity of system prompts and task keywords.
+
+---
+
+### Class: `TreeAgent`
+
+`TreeAgent` represents an individual agent responsible for handling a specific task. Agents are initialized with a **system prompt** and are responsible for dynamically determining their relevance to a given task.
+
+#### Attributes
+
+| **Attribute**            | **Type**         | **Description**                                                                 |
+|--------------------------|------------------|---------------------------------------------------------------------------------|
+| `system_prompt`          | `str`            | A string that defines the agent's area of expertise and task-handling capability.|
+| `llm`                    | `callable`       | The language model (LLM) used to process tasks (e.g., GPT-4).                    |
+| `agent_name`             | `str`            | The name of the agent.                                                          |
+| `system_prompt_embedding`| `tensor`         | Embedding of the system prompt for similarity-based task matching.               |
+| `relevant_keywords`      | `List[str]`      | Keywords dynamically extracted from the system prompt to assist in task matching.|
+| `distance`               | `Optional[float]`| The computed distance between agents based on embedding similarity.              |
+
+#### Methods
+
+| **Method**         | **Input**                       | **Output**         | **Description**                                                                 |
+|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------|
+| `calculate_distance(other_agent: TreeAgent)` | `other_agent: TreeAgent`   | `float`          | Calculates the cosine similarity between this agent and another agent.         |
+| `run_task(task: str)`                  | `task: str`                  | `Any`            | Executes the task, logs the input/output, and returns the result.               |
+| `is_relevant_for_task(task: str, threshold: float = 0.7)` | `task: str, threshold: float` | `bool`  | Checks if the agent is relevant for the task using keyword matching or embedding similarity.|
+
+---
+
+### Class: `Tree`
+
+`Tree` organizes multiple agents into a hierarchical structure, where agents are sorted based on their relevance to tasks.
+
+#### Attributes
+
+| **Attribute**            | **Type**         | **Description**                                                                 |
+|--------------------------|------------------|---------------------------------------------------------------------------------|
+| `tree_name`              | `str`            | The name of the tree (represents a domain of agents, e.g., "Financial Tree").    |
+| `agents`                 | `List[TreeAgent]`| List of agents belonging to this tree.                                           |
+
+#### Methods
+
+| **Method**         | **Input**                       | **Output**         | **Description**                                                                 |
+|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------|
+| `calculate_agent_distances()` | `None`                  | `None`             | Calculates and assigns distances between agents based on similarity of prompts. |
+| `find_relevant_agent(task: str)` | `task: str`           | `Optional[TreeAgent]` | Finds the most relevant agent for a task based on keyword and embedding similarity. |
+| `log_tree_execution(task: str, selected_agent: TreeAgent, result: Any)` | `task: str, selected_agent: TreeAgent, result: Any` | `None` | Logs details of the task execution by the selected agent.                      |
+
+---
+
+### Class: `ForestSwarm` 
+
+`ForestSwarm` is the main class responsible for managing multiple trees. It oversees task delegation by finding the most relevant tree and agent for a given task.
+
+#### Attributes
+
+| **Attribute**            | **Type**         | **Description**                                                                 |
+|--------------------------|------------------|---------------------------------------------------------------------------------|
+| `trees`                  | `List[Tree]`     | List of trees containing agents organized by domain.                             |
+
+#### Methods
+
+| **Method**         | **Input**                       | **Output**         | **Description**                                                                 |
+|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------|
+| `find_relevant_tree(task: str)` | `task: str`           | `Optional[Tree]`    | Searches across all trees to find the most relevant tree based on task requirements.|
+| `run(task: str)`                | `task: str`           | `Any`              | Executes the task by finding the most relevant agent from the relevant tree.    |
+
+## Full Code Example
+
+---
+
+## Example Workflow
+
+1. **Create Agents**: Agents are initialized with varying system prompts, representing different areas of expertise (e.g., stock analysis, tax filing).
+2. **Create Trees**: Agents are grouped into trees, with each tree representing a domain (e.g., "Financial Tree", "Investment Tree").
+3. **Run Task**: When a task is submitted, the system traverses through all trees and finds the most relevant agent to handle the task.
+4. **Task Execution**: The selected agent processes the task, and the result is returned.
+
+```plaintext
+Task: "Our company is incorporated in Delaware, how do we do our taxes for free?"
+```
+
+**Process**:
+- The system searches through the `Financial Tree` and `Investment Tree`.
+- The most relevant agent (likely the "Tax Filing Agent") is selected based on keyword matching and prompt similarity.
+- The task is processed, and the result is logged and returned.
+
+---
+
+## Analysis of the Swarm Architecture
+
+The **Swarm Architecture** leverages a hierarchical structure (forest) composed of individual trees, each containing agents specialized in specific domains. This design allows for:
+
+- **Modular and Scalable Organization**: By separating agents into trees, it is easy to expand or contract the system by adding or removing trees or agents.
+- **Task Specialization**: Each agent is specialized, which ensures that tasks are matched with the most appropriate agent based on relevance and expertise.
+- **Dynamic Matching**: The architecture uses both keyword-based and embedding-based matching to assign tasks, ensuring a high level of accuracy in agent selection.
+- **Logging and Accountability**: Each task execution is logged in detail, providing transparency and an audit trail of which agent handled which task and the results produced.
+- **Asynchronous Task Execution**: The architecture can be adapted for asynchronous task processing, making it scalable and suitable for large-scale task handling in real-time systems.
+
+---
+
+## Mermaid Diagram of the Swarm Architecture
+
+```mermaid
+graph TD
+    A[ForestSwarm] --> B[Financial Tree]
+    A --> C[Investment Tree]
+    
+    B --> D[Stock Analysis Agent]
+    B --> E[Financial Planning Agent]
+    B --> F[Retirement Strategy Agent]
+    
+    C --> G[Tax Filing Agent]
+    C --> H[Investment Strategy Agent]
+    C --> I[ROTH IRA Agent]
+
+    subgraph Tree Agents
+        D[Stock Analysis Agent]
+        E[Financial Planning Agent]
+        F[Retirement Strategy Agent]
+        G[Tax Filing Agent]
+        H[Investment Strategy Agent]
+        I[ROTH IRA Agent]
+    end
+```
+
+### Explanation of the Diagram
+
+- **ForestSwarm**: Represents the top-level structure managing multiple trees.
+- **Trees**: In the example, two trees exist—**Financial Tree** and **Investment Tree**—each containing agents related to specific domains.
+- **Agents**: Each agent within the tree is responsible for handling tasks in its area of expertise. Agents within a tree are organized based on their prompt similarity (distance).
+
+---
+
+### Summary
+
+This **Multi-Agent Tree Structure** provides an efficient, scalable, and accurate architecture for delegating and executing tasks based on domain-specific expertise. The combination of hierarchical organization, dynamic task matching, and logging ensures reliability, performance, and transparency in task execution.

forest_swarm_example.py

@@ -0,0 +1,44 @@
+from swarms.structs.tree_swarm import TreeAgent, Tree, ForestSwarm
+# Example Usage:
+
+# Create agents with varying system prompts and dynamically generated distances/keywords
+agents_tree1 = [
+    TreeAgent(
+        system_prompt="Stock Analysis Agent",
+        agent_name="Stock Analysis Agent",
+    ),
+    TreeAgent(
+        system_prompt="Financial Planning Agent",
+        agent_name="Financial Planning Agent",
+    ),
+    TreeAgent(
+        agent_name="Retirement Strategy Agent",
+        system_prompt="Retirement Strategy Agent",
+    ),
+]
+
+agents_tree2 = [
+    TreeAgent(
+        system_prompt="Tax Filing Agent",
+        agent_name="Tax Filing Agent",
+    ),
+    TreeAgent(
+        system_prompt="Investment Strategy Agent",
+        agent_name="Investment Strategy Agent",
+    ),
+    TreeAgent(
+        system_prompt="ROTH IRA Agent", agent_name="ROTH IRA Agent"
+    ),
+]
+
+# Create trees
+tree1 = Tree(tree_name="Financial Tree", agents=agents_tree1)
+tree2 = Tree(tree_name="Investment Tree", agents=agents_tree2)
+
+# Create the ForestSwarm
+multi_agent_structure = ForestSwarm(trees=[tree1, tree2])
+
+# Run a task
+task = "Our company is incorporated in delaware, how do we do our taxes for free?"
+output = multi_agent_structure.run(task)
+print(output)