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 **litellm-based embedding 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 using **litellm embeddings** and cosine similarity calculations.
The architecture allows for efficient task assignment by selecting the most relevant agent from a set of trees. Tasks are processed with agents selected based on task relevance, calculated by the similarity of system prompts and task keywords using **litellm embeddings** and cosine similarity calculations.
## Module Path: `swarms.structs.tree_swarm`
@ -11,24 +11,30 @@ The architecture allows for efficient task assignment by selecting the most rele
### Utility Functions
#### `extract_keywords(prompt: str, top_n: int = 5) -> List[str]`
Extracts relevant keywords from a text prompt using basic word splitting and frequency counting.
**Parameters:**
- `prompt` (str): The text to extract keywords from
- `top_n` (int): Maximum number of keywords to return
**Returns:**
- `List[str]`: List of extracted keywords sorted by frequency
Calculates the cosine similarity between two embedding vectors.
**Parameters:**
- `vec1` (List[float]): First embedding vector
- `vec2` (List[float]): Second embedding vector
**Returns:**
- `float`: Cosine similarity score between -1 and 1
- `float`: Cosine similarity score between 0 and 1
---
@ -36,25 +42,29 @@ Calculates the cosine similarity between two embedding vectors.
`TreeAgent` represents an individual agent responsible for handling a specific task. Agents are initialized with a **system prompt** and use **litellm embeddings** to dynamically determine their relevance to a given task.
| `__init__(name, description, system_prompt, model_name, agent_name, embedding_model_name, verbose, *args, **kwargs)` | Various initialization parameters | `None` | Initializes a TreeAgent with litellm embedding capabilities |
| `_get_embedding(text: str)` | `text: str` | `List[float]` | **Internal method to generate embeddings using litellm.** |
| `calculate_distance(other_agent: TreeAgent)` | `other_agent: TreeAgent` | `float` | Calculates the **cosine similarity distance** between this agent and another agent.|
| `run_task(task: str)` | `task: str` | `Any` | Executes the task, logs the input/output, and returns the result. |
| `run_task(task: str, img: str = None, *args, **kwargs)` | `task: str, img: str, *args, **kwargs` | `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 and litellm embedding similarity**.|
---
@ -63,17 +73,19 @@ Calculates the cosine similarity between two embedding vectors.
`Tree` organizes multiple agents into a hierarchical structure, where agents are sorted based on their relevance to tasks using **litellm embeddings**.
| `__init__(tree_name: str, agents: List[TreeAgent], verbose: bool = False)` | `tree_name: str, agents: List[TreeAgent], verbose: bool` | `None` | Initializes a tree of agents |
| `calculate_agent_distances()` | `None` | `None` | **Calculates and assigns distances between agents based on litellm embedding similarity of prompts.** |
| `find_relevant_agent(task: str)` | `task: str` | `Optional[TreeAgent]` | **Finds the most relevant agent for a task based on keyword and litellm 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. |
@ -84,7 +96,7 @@ Calculates the cosine similarity between two embedding vectors.
`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 using **litellm embeddings**.
| `__init__(name, description, trees, shared_memory, rules, verbose, *args, **kwargs)` | Various initialization parameters | `None` | Initialize a ForestSwarm with multiple trees of agents |
| `find_relevant_tree(task: str)` | `task: str` | `Optional[Tree]` | **Searches across all trees to find the most relevant tree based on litellm embedding similarity.**|
| `run(task: str, img: str = None, *args, **kwargs)` | `task: str, img: str, *args, **kwargs` | `Any` | **Executes the task by finding the most relevant agent from the relevant tree using litellm embeddings.**|
| `batched_run(tasks: List[str], *args, **kwargs)` | `tasks: List[str], *args, **kwargs` | `List[Any]` | **Executes multiple tasks by finding the most relevant agent for each task.**|
---
### Pydantic Models for Logging
#### `AgentLogInput`
Input log model for tracking agent task execution.
**Fields:**
- `log_id` (str): Unique identifier for the log entry
- `agent_name` (str): Name of the agent executing the task
- `task` (str): Description of the task being executed
- `timestamp` (datetime): When the task was started
#### `AgentLogOutput`
Output log model for tracking agent task completion.
**Fields:**
- `log_id` (str): Unique identifier for the log entry
- `agent_name` (str): Name of the agent that completed the task
- `result` (Any): Result/output from the task execution
- `timestamp` (datetime): When the task was completed
#### `TreeLog`
Tree execution log model for tracking tree-level operations.
**Fields:**
- `log_id` (str): Unique identifier for the log entry
- `tree_name` (str): Name of the tree that executed the task
- `task` (str): Description of the task that was executed
@ -145,49 +166,72 @@ from swarms.structs.tree_swarm import TreeAgent, Tree, ForestSwarm
# Create agents with varying system prompts and dynamically generated distances/keywords
agents_tree1 = [
TreeAgent(
name="Financial Advisor",
system_prompt="I am a financial advisor specializing in investment planning, retirement strategies, and tax optimization for individuals and businesses.",
agent_name="Financial Advisor",
verbose=True
),
TreeAgent(
name="Tax Expert",
system_prompt="I am a tax expert with deep knowledge of corporate taxation, Delaware incorporation benefits, and free tax filing options for businesses.",
agent_name="Tax Expert",
verbose=True
),
TreeAgent(
name="Retirement Planner",
system_prompt="I am a retirement planning specialist who helps individuals and businesses create comprehensive retirement strategies and investment plans.",
agent_name="Retirement Planner",
verbose=True
),
]
agents_tree2 = [
TreeAgent(
name="Stock Analyst",
system_prompt="I am a stock market analyst who provides insights on market trends, stock recommendations, and portfolio optimization strategies.",
agent_name="Stock Analyst",
verbose=True
),
TreeAgent(
name="Investment Strategist",
system_prompt="I am an investment strategist specializing in portfolio diversification, risk management, and market analysis.",
agent_name="Investment Strategist",
verbose=True
),
TreeAgent(
name="ROTH IRA Specialist",
system_prompt="I am a ROTH IRA specialist who helps individuals optimize their retirement accounts and tax advantages.",
- **Threshold-based Selection**: Configurable similarity thresholds for agent selection
- **Hybrid Matching**: Combines keyword matching with semantic similarity for optimal results
### **Dynamic Agent Organization**
- **Automatic Distance Calculation**: Agents are automatically organized by semantic similarity
- **Real-time Relevance**: Task relevance is calculated dynamically using current embeddings
- **Scalable Architecture**: Easy to add/remove agents and trees without manual configuration
### **Batch Processing**
- **Batched Execution**: Process multiple tasks efficiently using `batched_run` method
- **Parallel Processing**: Each task is processed independently with the most relevant agent
- **Result Aggregation**: All results are returned as a list for easy processing
---
## Analysis of the Swarm Architecture
@ -243,7 +298,7 @@ The **ForestSwarm Architecture** leverages a hierarchical structure (forest) com
- **Task Specialization**: Each agent is specialized, which ensures that tasks are matched with the most appropriate agent based on **litellm embedding similarity** and expertise.
- **Dynamic Matching**: The architecture uses both keyword-based and **litellm 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.
- **Batch Processing**: The architecture supports efficient batch processing of multiple tasks simultaneously.
---
@ -274,6 +329,13 @@ graph TD
P --> Q[Execute Task]
Q --> R[Log Results]
end
subgraph Batch Processing
S[Multiple Tasks] --> T[Process Each Task]
T --> U[Find Relevant Agent per Task]
U --> V[Execute All Tasks]
V --> W[Return Results List]
end
```
### Explanation of the Diagram
@ -283,6 +345,7 @@ graph TD
- **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 **litellm embedding similarity** (distance).
- **Embedding Process**: Shows how **litellm embeddings** are used for similarity calculations and agent selection.
- **Task Processing**: Illustrates the complete workflow from task input to result logging.
- **Batch Processing**: Shows how multiple tasks can be processed efficiently using the `batched_run` method.
This **ForestSwarm Architecture** provides an efficient, scalable, and accurate architecture for delegating and executing tasks based on domain-specific expertise. The combination of hierarchical organization, **litellm-based semantic similarity**, dynamic task matching, and comprehensive logging ensures reliability, performance, and transparency in task execution.
**Key Advantages:**
- **High Accuracy**: litellm embeddings provide superior semantic understanding
- **Scalability**: Easy to add new agents, trees, and domains
- **Flexibility**: Configurable similarity thresholds and embedding models
- **Robustness**: Comprehensive error handling and fallback mechanisms
- **Transparency**: Detailed logging and audit trails for all operations
- **Batch Processing**: Efficient processing of multiple tasks simultaneously
- **Verbose Logging**: Comprehensive logging at all levels for debugging and monitoring
Kye Gomez
2 days ago