Package com.tnsai.coordination.observability

Class BottleneckDetector

java.lang.Object
com.tnsai.coordination.observability.BottleneckDetector
public class BottleneckDetector extends Object
Analyzes an InteractionGraph to detect performance bottlenecks in multi-agent systems.

Detects the following bottleneck types:

  • OVERLOADED - Agent with disproportionately high in-degree
  • SINGLE_POINT_FAILURE - Agent whose removal disconnects the graph
  • IDLE - Agent with very low activity
  • COMMUNICATION_HOT_SPOT - Edge with disproportionately high weight
  • UNBALANCED_LOAD - High variance in agent activity levels

Usage Example


 BottleneckDetector detector = new BottleneckDetector(graph);
 List<Bottleneck> bottlenecks = detector.detect();
 double health = detector.getHealthScore();

  • Constructor Details

    • BottleneckDetector

      public BottleneckDetector(InteractionGraph graph)
      Creates a detector for the given interaction graph.
      Parameters:
      graph - interaction graph to analyze

  • Method Details

    • detect

      public List<BottleneckDetector.Bottleneck> detect()
      Runs all detection algorithms with default thresholds.
      Returns:
      list of all detected bottlenecks

    • detectOverloaded

      public List<BottleneckDetector.Bottleneck> detectOverloaded(double thresholdMultiplier)
      Detects agents with disproportionately high in-degree.

      An agent is overloaded if its in-degree exceeds the mean in-degree multiplied by the threshold.

      Parameters:
      thresholdMultiplier - multiplier for mean in-degree (default 2.0)
      Returns:
      list of overloaded bottlenecks

    • detectIdle

      public List<BottleneckDetector.Bottleneck> detectIdle(double minActivity)
      Detects agents with very low activity.

      An agent is idle if its out-degree is less than minActivity * mean(outDegree).

      Parameters:
      minActivity - minimum activity ratio relative to mean (default 0.1)
      Returns:
      list of idle bottlenecks

    • detectSinglePointsOfFailure

      public List<BottleneckDetector.Bottleneck> detectSinglePointsOfFailure()
      Detects agents whose removal would disconnect the graph.

      Uses BFS reachability: removes each agent and checks if remaining agents are still connected.

      Returns:
      list of single-point-of-failure bottlenecks

    • detectCommunicationHotSpots

      public List<BottleneckDetector.Bottleneck> detectCommunicationHotSpots(double thresholdMultiplier)
      Detects edges with disproportionately high weight.

      An edge is a hot spot if its weight exceeds the mean edge weight multiplied by the threshold.

      Parameters:
      thresholdMultiplier - multiplier for mean edge weight (default 3.0)
      Returns:
      list of communication hot spot bottlenecks

    • detectUnbalancedLoad

      public List<BottleneckDetector.Bottleneck> detectUnbalancedLoad(double maxVarianceRatio)
      Detects unbalanced load across agents.

      Load is unbalanced if the ratio of max activity to min activity exceeds the threshold, where activity = in-degree + out-degree.

      Parameters:
      maxVarianceRatio - maximum allowed ratio (default 2.0)
      Returns:
      list of unbalanced load bottlenecks (one per detection, not per agent)

    • getHealthScore

      public double getHealthScore()
      Computes an overall health score for the agent group.

      Score ranges from 0.0 (unhealthy) to 1.0 (healthy). Formula: 1.0 - (bottleneck_count * severity_sum) / (node_count * 10), clamped to [0, 1].

      Returns:
      health score between 0.0 and 1.0