SwarmMatcher

SwarmMatcher has been removed from the swarms package (swarms/structs/swarm_matcher.py was deleted, along with its torch/sentence-transformers dependencies) and migrated to a separate, not-yet-published swarms-utils package. As of the current codebase, from swarms.structs.swarm_matcher import SwarmMatcher will raise ModuleNotFoundError — the class is not importable from swarms at all. The parameter and method reference below reflects the last known implementation prior to removal and cannot be verified against current source. Treat this page as historical until SwarmMatcher is reintroduced or its replacement package is published.

Overview

The SwarmMatcher utilizes transformer-based embeddings to determine the best swarm architecture for a given task. By analyzing the semantic meaning of task descriptions and comparing them to known swarm types, it can intelligently select the optimal swarm configuration for any task.

Workflow

Installation

pip install -U swarms

Attributes

SwarmMatcherConfig

str

default:"sentence-transformers/all-MiniLM-L6-v2"

The transformer model to use for generating embeddings.

int

default:"512"

The dimension of the embedding vectors.

SwarmType

str

required

The name of the swarm type.

str

required

A detailed description of the swarm type’s capabilities and ideal use cases.

Optional[List[float]]

default:"None"

The generated embedding vector for this swarm type (auto-populated).

Methods

init()

Initializes the SwarmMatcher with a configuration.

def __init__(self, config: SwarmMatcherConfig)

Parameters:

config (SwarmMatcherConfig): Configuration object for the matcher

get_embedding()

Generates an embedding vector for a given text using the configured model.

def get_embedding(self, text: str) -> np.ndarray

Parameters:

text (str): The text to embed

Returns: np.ndarray - The embedding vector

add_swarm_type()

Adds a swarm type to the matcher, generating an embedding for its description.

def add_swarm_type(self, swarm_type: SwarmType)

Parameters:

swarm_type (SwarmType): The swarm type to add

find_best_match()

Finds the best matching swarm type for a given task.

def find_best_match(self, task: str) -> Tuple[str, float]

Parameters:

task (str): The task description

Returns: Tuple[str, float] - The name of the best matching swarm type and the similarity score

auto_select_swarm()

Automatically selects the best swarm type for a given task.

def auto_select_swarm(self, task: str) -> str

Parameters:

task (str): The task description

Returns: str - The name of the selected swarm type

run_multiple()

Matches multiple tasks to swarm types in batch.

def run_multiple(self, tasks: List[str]) -> List[str]

Parameters:

tasks (List[str]): A list of task descriptions

Returns: List[str] - A list of selected swarm type names

save_swarm_types()

Saves the registered swarm types to a JSON file.

def save_swarm_types(self, filename: str)

Parameters:

filename (str): Path where the swarm types will be saved

load_swarm_types()

Loads swarm types from a JSON file.

def load_swarm_types(self, filename: str)

Parameters:

filename (str): Path to the JSON file containing swarm types

Available Swarm Types

SwarmMatcher comes with several pre-defined swarm types:

Swarm Type	Description
AgentRearrange	Optimize agent order and rearrange flow for multi-step tasks, ensuring efficient task allocation and minimizing bottlenecks.
MixtureOfAgents	Combine diverse expert agents for comprehensive analysis, fostering a collaborative approach to problem-solving and leveraging individual strengths.
SpreadSheetSwarm	Collaborative data processing and analysis in a spreadsheet-like environment, facilitating real-time data sharing and visualization.
SequentialWorkflow	Execute tasks in a step-by-step, sequential process workflow, ensuring a logical and methodical approach to task execution.
ConcurrentWorkflow	Process multiple tasks or data sources concurrently in parallel, maximizing productivity and reducing processing time.

Usage Examples

Simple Matching

from swarms import swarm_matcher

# Use the simplified function to match a task to a swarm type
swarm_type = swarm_matcher("Analyze this dataset and create visualizations")
print(f"Selected swarm type: {swarm_type}")

Batch Matching

from swarms import swarm_matcher

# Match tasks to swarm types
tasks = [
    "Analyze this dataset and create visualizations",
    "Coordinate multiple agents to tackle different aspects of a problem",
    "Process these 10 PDF files in sequence",
    "Handle these data processing tasks in parallel"
]

for task in tasks:
    swarm_type = swarm_matcher(task)
    print(f"Task: {task}")
    print(f"Selected swarm: {swarm_type}\n")

Advanced Usage with Custom Configuration

from swarms import SwarmMatcher, SwarmMatcherConfig, SwarmType

# Create a configuration
config = SwarmMatcherConfig(
    model_name="sentence-transformers/all-MiniLM-L6-v2",
    embedding_dim=512
)

# Initialize the matcher
matcher = SwarmMatcher(config)

# Add a custom swarm type
custom_swarm = SwarmType(
    name="CustomSwarm",
    description="A specialized swarm for handling specific domain tasks with expert knowledge."
)
matcher.add_swarm_type(custom_swarm)

# Find the best match for a task
best_match, score = matcher.find_best_match("Process natural language and extract key insights")
print(f"Best match: {best_match}, Score: {score}")

# Auto-select a swarm type
selected_swarm = matcher.auto_select_swarm("Create data visualizations from this CSV file")
print(f"Selected swarm: {selected_swarm}")

Custom Swarm Types

from swarms import SwarmMatcher, SwarmMatcherConfig, SwarmType

# Create configuration and matcher
config = SwarmMatcherConfig()
matcher = SwarmMatcher(config)

# Define custom swarm types
swarm_types = [
    SwarmType(
        name="DataAnalysisSwarm",
        description="Specialized in processing and analyzing large datasets, performing statistical analysis, and extracting insights from complex data."
    ),
    SwarmType(
        name="CreativeWritingSwarm",
        description="Optimized for creative content generation, storytelling, and producing engaging written material with consistent style and tone."
    ),
    SwarmType(
        name="ResearchSwarm",
        description="Focused on deep research tasks, synthesizing information from multiple sources, and producing comprehensive reports on complex topics."
    )
]

# Add swarm types
for swarm_type in swarm_types:
    matcher.add_swarm_type(swarm_type)

# Save the swarm types for future use
matcher.save_swarm_types("custom_swarm_types.json")

# Use the matcher
task = "Research quantum computing advances in the last 5 years"
best_match = matcher.auto_select_swarm(task)
print(f"Selected swarm type: {best_match}")

How It Works

SwarmMatcher uses a transformer-based model to generate embeddings (vector representations) of both the task descriptions and the swarm type descriptions. It then calculates the similarity between these embeddings to determine which swarm type is most semantically similar to the given task. The matching process follows these steps:

The task description is converted to an embedding vector
Each swarm type’s description is converted to an embedding vector
The similarity between the task embedding and each swarm type embedding is calculated
The swarm type with the highest similarity score is selected

This approach ensures that the matcher can understand the semantic meaning of tasks, not just keyword matching, resulting in more accurate swarm type selection.

Source Code

View the source code on GitHub

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Overview

Workflow

Installation

Attributes

SwarmMatcherConfig

SwarmType

Methods

init()

get_embedding()

add_swarm_type()

find_best_match()

auto_select_swarm()

run_multiple()

save_swarm_types()

load_swarm_types()

Available Swarm Types

Usage Examples

Simple Matching

Batch Matching

Advanced Usage with Custom Configuration

Custom Swarm Types

How It Works

Source Code

​Overview

​Workflow

​Installation

​Attributes

​SwarmMatcherConfig

​SwarmType

​Methods

​__init__()

​get_embedding()

​add_swarm_type()

​find_best_match()

​auto_select_swarm()

​run_multiple()

​save_swarm_types()

​load_swarm_types()

​Available Swarm Types

​Usage Examples

​Simple Matching

​Batch Matching

​Advanced Usage with Custom Configuration

​Custom Swarm Types

​How It Works

​Source Code

Overview

Workflow

Installation

Attributes

SwarmMatcherConfig

SwarmType

Methods

init()

get_embedding()

add_swarm_type()

find_best_match()

auto_select_swarm()

run_multiple()

save_swarm_types()

load_swarm_types()

Available Swarm Types

Usage Examples

Simple Matching

Batch Matching

Advanced Usage with Custom Configuration

Custom Swarm Types

How It Works

Source Code