# 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. ## Module Path: `swarms.structs.tree_swarm` --- ### 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 ```python 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) ``` --- ## 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.