Package com.tnsai.coordination.groups.swarm

Interface Swarm

All Superinterfaces:
com.tnsai.agents.groups.AgentGroup
All Known Implementing Classes:
DefaultSwarm
public interface Swarm extends com.tnsai.agents.groups.AgentGroup
Swarm is a decentralized agent group with emergent behavior.

Unlike Teams with centralized coordination, Swarms use local interactions and stigmergy (indirect communication via environment) to achieve collective intelligence.

Key Characteristics

  • Decentralized - No single leader, local decisions
  • Emergent Behavior - Complex patterns from simple rules
  • Self-Organizing - Adapts without explicit control
  • Robust - Tolerant to individual failures

Usage Example


 Swarm swarm = Swarm.builder()
     .name("Search Swarm")
     .behavior(SwarmBehavior.EXPLORATION)
     .pheromoneDecay(0.1)
     .neighborRadius(3)
     .add(agent1, agent2, agent3)
     .build();

 // Swarm explores collectively
 SwarmResult result = swarm.explore("Find relevant documents");

 // Or solve a problem collectively
 SwarmResult solved = swarm.solve("Optimize this configuration");
See Also:

  • Method Details

    • getBehavior

      SwarmBehavior getBehavior()
      Gets the current swarm behavior.
      Returns:
      behavior type

    • setBehavior

      void setBehavior(SwarmBehavior behavior)
      Sets the swarm behavior.
      Parameters:
      behavior - new behavior

    • getIntelligence

      SwarmIntelligence getIntelligence()
      Gets the swarm intelligence strategy.
      Returns:
      intelligence strategy

    • getNeighborDetection

      NeighborDetection getNeighborDetection()
      Gets the neighbor detection strategy.
      Returns:
      neighbor detection

    • depositPheromone

      void depositPheromone(String location, PheromoneType type, double intensity)
      Deposits a pheromone at the specified location.

      Pheromones are indirect signals that influence other swarm members' behavior.

      Parameters:
      location - location identifier
      type - pheromone type
      intensity - signal strength (0.0 to 1.0)

    • getPheromoneIntensity

      double getPheromoneIntensity(String location, PheromoneType type)
      Gets the pheromone intensity at a location.
      Parameters:
      location - location identifier
      type - pheromone type
      Returns:
      intensity (0.0 to 1.0)

    • getPheromonesAt

      Map<PheromoneType,Double> getPheromonesAt(String location)
      Gets all pheromones at a location.
      Parameters:
      location - location identifier
      Returns:
      map of pheromone types to intensities

    • getPheromoneDecay

      double getPheromoneDecay()
      Gets the pheromone decay rate.
      Returns:
      decay rate per tick

    • decayPheromones

      void decayPheromones()
      Triggers pheromone decay across all locations.

    • getNeighbors

      List<com.tnsai.agents.Agent> getNeighbors(String agentId)
      Gets neighbors of an agent within detection radius.
      Parameters:
      agentId - agent to check
      Returns:
      list of neighboring agents

    • getNeighborRadius

      int getNeighborRadius()
      Gets the neighbor detection radius.
      Returns:
      radius (interpretation depends on detection strategy)

    • setNeighborRadius

      void setNeighborRadius(int radius)
      Sets the neighbor detection radius.
      Parameters:
      radius - new radius

    • explore

      SwarmResult explore(String task)
      Executes a collective exploration task.

      Agents spread out and share discoveries via pheromones.

      Parameters:
      task - exploration task
      Returns:
      collective result

    • explore

      SwarmResult explore(String task, Map<String,Object> context)
      Executes a collective exploration task with context.
      Parameters:
      task - exploration task
      context - additional context
      Returns:
      collective result

    • solve

      SwarmResult solve(String problem)
      Executes a collective optimization/solving task.

      Agents collaborate using swarm intelligence algorithms.

      Parameters:
      problem - problem description
      Returns:
      optimized solution

    • solve

      SwarmResult solve(String problem, Map<String,Object> context)
      Executes a collective optimization with context.
      Parameters:
      problem - problem description
      context - additional context
      Returns:
      optimized solution

    • exploreAsync

      CompletableFuture<SwarmResult> exploreAsync(String task)
      Async exploration.
      Parameters:
      task - exploration task
      Returns:
      future result

    • solveAsync

      CompletableFuture<SwarmResult> solveAsync(String problem)
      Async solving.
      Parameters:
      problem - problem description
      Returns:
      future result

    • getState

      SwarmState getState()
      Gets current swarm state snapshot.
      Returns:
      swarm state

    • getEnvironment

      SwarmEnvironment getEnvironment()
      Gets the shared environment/blackboard.
      Returns:
      shared environment

    • tick

      void tick()
      Triggers one swarm tick (update cycle).

      During a tick:

      • Pheromones decay
      • Agents update positions
      • Neighbors are recalculated
      • Behaviors are executed

    • run

      void run(Duration duration, Duration tickInterval)
      Runs the swarm for specified duration.
      Parameters:
      duration - how long to run
      tickInterval - time between ticks

    • stop

      void stop()
      Stops the swarm execution.
      Specified by:
      stop in interface com.tnsai.agents.groups.AgentGroup

    • isRunning

      boolean isRunning()
      Checks if swarm is currently running.
      Returns:
      true if running

    • builder

      static SwarmBuilder builder()
      Creates a new SwarmBuilder.
      Returns:
      builder