Hybrid Hierarchical-Cluster Swarm [HHCS]¶

The Hybrid Hierarchical-Cluster Swarm (HHCS) is an advanced AI orchestration architecture that combines hierarchical decision-making with parallel processing capabilities. HHCS enables complex task solving by dynamically routing tasks to specialized agent swarms based on their expertise and capabilities.

Purpose¶

HHCS addresses the challenge of efficiently solving diverse and complex tasks by:

Intelligently routing tasks to the most appropriate specialized swarms
Enabling parallel processing of multifaceted problems
Maintaining a clear hierarchy for effective decision-making
Combining outputs from multiple specialized agents for comprehensive solutions

Key Features¶

Router-based task distribution: Central router agent analyzes incoming tasks and directs them to appropriate specialized swarms
Hybrid architecture: Combines hierarchical control with clustered specialization
Parallel processing: Multiple swarms can work simultaneously on different aspects of complex tasks
Flexible swarm types: Supports both sequential and concurrent workflows within swarms
Comprehensive result aggregation: Collects and combines outputs from all contributing swarms

Diagram¶

The HHCS architecture follows a hierarchical structure with the router agent at the top level, specialized swarms at the middle level, and individual agents at the bottom level.

flowchart TD
    Start([Task Input]) --> RouterAgent[Router Agent]
    RouterAgent --> Analysis{Task Analysis}

    Analysis -->|Analyze Requirements| Selection[Swarm Selection]
    Selection -->|Select Best Swarm| Route[Route Task]

    Route --> Swarm1[Swarm 1]
    Route --> Swarm2[Swarm 2]
    Route --> SwarmN[Swarm N...]

    Swarm1 -->|Process Task| Result1[Swarm 1 Output]
    Swarm2 -->|Process Task| Result2[Swarm 2 Output]
    SwarmN -->|Process Task| ResultN[Swarm N Output]

    Result1 --> Conversation[Conversation History]
    Result2 --> Conversation
    ResultN --> Conversation

    Conversation --> Output([Final Output])

    subgraph Router Decision Process
        Analysis
        Selection
    end

    subgraph Parallel Task Processing
        Swarm1
        Swarm2
        SwarmN
    end

    subgraph Results Collection
        Result1
        Result2
        ResultN
        Conversation
    end

`HybridHierarchicalClusterSwarm` Constructor Arguments¶

Parameter	Type	Default	Description
`name`	string	"Hybrid Hierarchical-Cluster Swarm"	The name of the swarm instance
`description`	string	"A swarm that uses a hybrid hierarchical-peer model to solve complex tasks."	Brief description of the swarm's functionality
`swarms`	List[SwarmRouter]	[]	List of available swarm routers
`max_loops`	integer	1	Maximum number of processing loops
`output_type`	string	"list"	Format for output (e.g., "list", "json")
`router_agent_model_name`	string	"gpt-4o-mini"	LLM model used by the router agent

Methods¶

Method	Parameters	Return Type	Description
`run`	`task` (str)	str	Processes a single task through the swarm system
`batched_run`	`tasks` (List[str])	List[str]	Processes multiple tasks in parallel
`find_swarm_by_name`	`swarm_name` (str)	SwarmRouter	Retrieves a swarm by its name
`route_task`	`swarm_name` (str), `task_description` (str)	None	Routes a task to a specific swarm
`get_swarms_info`	None	str	Returns formatted information about all available swarms

Full Example¶

from swarms import Agent, SwarmRouter
from swarms.structs.hybrid_hiearchical_peer_swarm import (
    HybridHierarchicalClusterSwarm,
)


# Core Legal Agent Definitions with short, simple prompts
litigation_agent = Agent(
    agent_name="Litigator",
    system_prompt="You handle lawsuits. Analyze facts, build arguments, and develop case strategy.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

corporate_agent = Agent(
    agent_name="Corporate-Attorney",
    system_prompt="You handle business law. Advise on corporate structure, governance, and transactions.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

ip_agent = Agent(
    agent_name="IP-Attorney",
    system_prompt="You protect intellectual property. Handle patents, trademarks, copyrights, and trade secrets.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

employment_agent = Agent(
    agent_name="Employment-Attorney",
    system_prompt="You handle workplace matters. Address hiring, termination, discrimination, and labor issues.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

paralegal_agent = Agent(
    agent_name="Paralegal",
    system_prompt="You assist attorneys. Conduct research, draft documents, and organize case files.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

doc_review_agent = Agent(
    agent_name="Document-Reviewer",
    system_prompt="You examine documents. Extract key information and identify relevant content.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

# Practice Area Swarm Routers
litigation_swarm = SwarmRouter(
    name="litigation-practice",
    description="Handle all aspects of litigation",
    agents=[litigation_agent, paralegal_agent, doc_review_agent],
    swarm_type="SequentialWorkflow",
)

corporate_swarm = SwarmRouter(
    name="corporate-practice",
    description="Handle business and corporate legal matters",
    agents=[corporate_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

ip_swarm = SwarmRouter(
    name="ip-practice",
    description="Handle intellectual property matters",
    agents=[ip_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

employment_swarm = SwarmRouter(
    name="employment-practice",
    description="Handle employment and labor law matters",
    agents=[employment_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

# Cross-functional Swarm Router
m_and_a_swarm = SwarmRouter(
    name="mergers-acquisitions",
    description="Handle mergers and acquisitions",
    agents=[
        corporate_agent,
        ip_agent,
        employment_agent,
        doc_review_agent,
    ],
    swarm_type="ConcurrentWorkflow",
)

dispute_swarm = SwarmRouter(
    name="dispute-resolution",
    description="Handle complex disputes requiring multiple specialties",
    agents=[litigation_agent, corporate_agent, doc_review_agent],
    swarm_type="ConcurrentWorkflow",
)


hybrid_hiearchical_swarm = HybridHierarchicalClusterSwarm(
    name="hybrid-hiearchical-swarm",
    description="A hybrid hiearchical swarm that uses a hybrid hiearchical peer model to solve complex tasks.",
    swarms=[
        litigation_swarm,
        corporate_swarm,
        ip_swarm,
        employment_swarm,
        m_and_a_swarm,
        dispute_swarm,
    ],
    max_loops=1,
    router_agent_model_name="gpt-4o-mini",
)


if __name__ == "__main__":
    hybrid_hiearchical_swarm.run(
        "What is the best way to file for a patent? for ai technology "
    )