ForestSwarm

Documentation Index

Fetch the complete documentation index at: https://docs.swarms.world/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Installation

pip install -U swarms

​

Utility Functions

​

extract_keywords()

def extract_keywords(prompt: str, top_n: int = 5) -> List[str]

• prompt (str): The text to extract keywords from
• top_n (int): Maximum number of keywords to return

​

cosine_similarity()

def cosine_similarity(vec1: List[float], vec2: List[float]) -> float

• vec1 (List[float]): First embedding vector
• vec2 (List[float]): Second embedding vector

​

TreeAgent

​

TreeAgent Attributes

​

TreeAgent Methods

​

calculate_distance()

def calculate_distance(self, other_agent: TreeAgent) -> float

• other_agent (TreeAgent): Another agent to compare with

​

run_task()

def run_task(self, task: str, img: str = None, *args, **kwargs) -> Any

• task (str): The task to execute
• img (str, optional): Optional image input

​

is_relevant_for_task()

def is_relevant_for_task(self, task: str, threshold: float = 0.7) -> bool

• task (str): The task to check relevance for
• threshold (float): Similarity threshold (default: 0.7)

​

Tree

​

Tree Attributes

​

Tree Methods

​

calculate_agent_distances()

def calculate_agent_distances(self) -> None

​

find_relevant_agent()

def find_relevant_agent(self, task: str) -> Optional[TreeAgent]

• task (str): The task to find a relevant agent for

​

log_tree_execution()

def log_tree_execution(self, task: str, selected_agent: TreeAgent, result: Any) -> None

• task (str): The executed task description
• selected_agent (TreeAgent): The agent that executed the task
• result (Any): The result of the execution

​

ForestSwarm Attributes

​

ForestSwarm Methods

​

find_relevant_tree()

def find_relevant_tree(self, task: str) -> Optional[Tree]

• task (str): The task to find a relevant tree for

​

run()

def run(self, task: str, img: str = None, *args, **kwargs) -> Any

• task (str): The task to execute
• img (str, optional): Optional image input

​

batched_run()

def batched_run(self, tasks: List[str], *args, **kwargs) -> List[Any]

• tasks (List[str]): List of tasks to execute

​

Usage Examples

​

Full Working Example

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.",
        agent_name="ROTH IRA Specialist",
        verbose=True
    ),
]

# Create trees
tree1 = Tree(tree_name="Financial Services Tree", agents=agents_tree1, verbose=True)
tree2 = Tree(tree_name="Investment & Trading Tree", agents=agents_tree2, verbose=True)

# Create the ForestSwarm
forest_swarm = ForestSwarm(
    name="Financial Services Forest",
    description="A comprehensive financial services multi-agent system",
    trees=[tree1, tree2],
    verbose=True
)

# Run a task
task = "Our company is incorporated in Delaware, how do we do our taxes for free?"
output = forest_swarm.run(task)
print(output)

# Run multiple tasks
tasks = [
    "What are the best investment strategies for retirement?",
    "How do I file taxes for my Delaware corporation?",
    "What's the current market outlook for tech stocks?"
]
results = forest_swarm.batched_run(tasks)
for i, result in enumerate(results):
    print(f"Task {i+1} result: {result}")

​

How It Works

1. Create Agents: Agents are initialized with varying system prompts, representing different areas of expertise (e.g., financial planning, tax filing).
2. Generate Embeddings: Each agent’s system prompt is converted to litellm embeddings for semantic similarity calculations.
3. Create Trees: Agents are grouped into trees, with each tree representing a domain (e.g., “Financial Services Tree”, “Investment & Trading Tree”).
4. Calculate Distances: litellm embeddings are used to calculate semantic distances between agents within each tree.
5. Run Task: When a task is submitted, the system:
   • Generates litellm embeddings for the task
   • Searches through all trees using cosine similarity
   • Finds the most relevant agent based on embedding similarity and keyword matching
6. Task Execution: The selected agent processes the task, and the result is returned and logged.
7. Batched Processing: Multiple tasks can be processed using the batched_run method for efficient batch processing.

​

Key Features

​

litellm Integration

• Embedding Generation: Uses litellm’s embedding() function for generating high-quality embeddings
• Model Flexibility: Supports various embedding models (default: “text-embedding-ada-002”)
• Error Handling: Robust fallback mechanisms for embedding failures

​

Semantic Similarity

• Cosine Similarity: Implements efficient cosine similarity calculations for vector comparisons
• 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

​

Logging Models

​

AgentLogInput

​

AgentLogOutput

​

TreeLog

​

Architecture Analysis

• 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 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.
• Batch Processing: The architecture supports efficient batch processing of multiple tasks simultaneously.

​

Source Code