Skip to content

MatrixSwarm

The MatrixSwarm class provides a framework for managing and operating on matrices of AI agents, enabling matrix-like operations similar to linear algebra. This allows for complex agent interactions and parallel processing capabilities.

Overview

MatrixSwarm treats AI agents as elements in a matrix, allowing for operations like addition, multiplication, and transposition. This approach enables sophisticated agent orchestration and parallel processing patterns.

Installation

pip3 install -U swarms

Basic Usage

from swarms import Agent
from swarms.matrix import MatrixSwarm

# Create a 2x2 matrix of agents
agents = [
    [Agent(agent_name="Agent-0-0"), Agent(agent_name="Agent-0-1")],
    [Agent(agent_name="Agent-1-0"), Agent(agent_name="Agent-1-1")]
]

# Initialize the matrix
matrix = MatrixSwarm(agents)

Class Constructor

def __init__(self, agents: List[List[Agent]])

Parameters

  • agents (List[List[Agent]]): A 2D list of Agent instances representing the matrix.

Raises

  • ValueError: If the input is not a valid 2D list of Agent instances.

Methods

transpose()

Transposes the matrix of agents by swapping rows and columns.

def transpose(self) -> MatrixSwarm

Returns

  • MatrixSwarm: A new MatrixSwarm instance with transposed dimensions.

add(other)

Performs element-wise addition of two agent matrices.

def add(self, other: MatrixSwarm) -> MatrixSwarm

Parameters

  • other (MatrixSwarm): Another MatrixSwarm instance to add.

Returns

  • MatrixSwarm: A new MatrixSwarm resulting from the addition.

Raises

  • ValueError: If matrix dimensions are incompatible.

scalar_multiply(scalar)

Scales the matrix by duplicating agents along rows.

def scalar_multiply(self, scalar: int) -> MatrixSwarm

Parameters

  • scalar (int): The multiplication factor.

Returns

  • MatrixSwarm: A new MatrixSwarm with scaled dimensions.

multiply(other, inputs)

Performs matrix multiplication (dot product) between two agent matrices.

def multiply(self, other: MatrixSwarm, inputs: List[str]) -> List[List[AgentOutput]]

Parameters

  • other (MatrixSwarm): The second MatrixSwarm for multiplication.
  • inputs (List[str]): Input queries for the agents.

Returns

  • List[List[AgentOutput]]: Matrix of operation results.

Raises

  • ValueError: If matrix dimensions are incompatible for multiplication.

subtract(other)

Performs element-wise subtraction of two agent matrices.

def subtract(self, other: MatrixSwarm) -> MatrixSwarm

Parameters

  • other (MatrixSwarm): Another MatrixSwarm to subtract.

Returns

  • MatrixSwarm: A new MatrixSwarm resulting from the subtraction.

identity(size)

Creates an identity matrix of agents.

def identity(self, size: int) -> MatrixSwarm

Parameters

  • size (int): Size of the identity matrix (NxN).

Returns

  • MatrixSwarm: An identity MatrixSwarm.

determinant()

Computes the determinant of a square agent matrix.

def determinant(self) -> Any

Returns

  • Any: The determinant result.

Raises

  • ValueError: If the matrix is not square.

save_to_file(path)

Saves the matrix structure and metadata to a JSON file.

def save_to_file(self, path: str) -> None

Parameters

  • path (str): File path for saving the matrix data.

Extended Example

Here's a comprehensive example demonstrating various MatrixSwarm operations:

from swarms import Agent
from swarms.matrix import MatrixSwarm

# Create agents with specific configurations
agents = [
    [
        Agent(
            agent_name=f"Agent-{i}-{j}",
            system_prompt="Your system prompt here",
            model_name="gpt-4",
            max_loops=1,
            verbose=True
        ) for j in range(2)
    ] for i in range(2)
]

# Initialize matrix
matrix = MatrixSwarm(agents)

# Example operations
transposed = matrix.transpose()
scaled = matrix.scalar_multiply(2)

# Run operations with inputs
inputs = ["Query 1", "Query 2"]
results = matrix.multiply(transposed, inputs)

# Save results
matrix.save_to_file("matrix_results.json")

Output Schema

The AgentOutput class defines the structure for operation results:

class AgentOutput(BaseModel):
    agent_name: str
    input_query: str
    output_result: Any
    metadata: dict

Best Practices

  1. Initialization
  2. Ensure all agents in the matrix are properly configured before initialization
  3. Validate matrix dimensions for your use case

  4. Operation Performance

  5. Consider computational costs for large matrices
  6. Use appropriate batch sizes for inputs

  7. Error Handling

  8. Implement proper error handling for agent operations
  9. Validate inputs before matrix operations

  10. Resource Management

  11. Monitor agent resource usage in large matrices
  12. Implement proper cleanup procedures

Limitations

  • Matrix operations are constrained by the underlying agent capabilities
  • Performance may vary based on agent configuration and complexity
  • Resource usage scales with matrix dimensions

See Also