Package com.tnsai.coordination.observability

Class InteractionGraph

java.lang.Object
com.tnsai.coordination.observability.InteractionGraph
public class InteractionGraph extends Object
Directed weighted graph representing inter-agent interactions.

Nodes represent agents and edges represent interactions such as messages, task assignments, or other communication events between agents. Edge weights indicate the frequency or intensity of interactions.

This class is thread-safe and uses ConcurrentHashMap for internal storage.

Usage Example


 InteractionGraph graph = new InteractionGraph();
 graph.addNode("agent-1");
 graph.addNode("agent-2");
 graph.addEdge("agent-1", "agent-2", "message");
 graph.incrementEdge("agent-1", "agent-2", "message");

 double outDegree = graph.getOutDegree("agent-1"); // 2.0
 String dot = graph.toDotFormat();

  • Constructor Details

    • InteractionGraph

      public InteractionGraph()

  • Method Details

    • addNode

      public void addNode(String agentId)
      Adds a node with no attributes.
      Parameters:
      agentId - unique agent identifier

    • addNode

      public void addNode(String agentId, Map<String,Object> attributes)
      Adds a node with attributes. If the node already exists, attributes are merged.
      Parameters:
      agentId - unique agent identifier
      attributes - node attributes

    • hasNode

      public boolean hasNode(String agentId)
      Checks if a node exists in the graph.
      Parameters:
      agentId - agent identifier to check
      Returns:
      true if the node exists

    • getNode

      public Optional<InteractionGraph.Node> getNode(String agentId)
      Gets a node by agent ID.
      Parameters:
      agentId - agent identifier
      Returns:
      the node if found

    • getNodeIds

      public Set<String> getNodeIds()
      Gets all node IDs in the graph.
      Returns:
      unmodifiable set of agent IDs

    • nodeCount

      public int nodeCount()
      Returns the number of nodes in the graph.
      Returns:
      node count

    • addEdge

      public void addEdge(String from, String to, String type)
      Adds an edge with default weight of 1.0.
      Parameters:
      from - source agent ID
      to - target agent ID
      type - interaction type

    • addEdge

      public void addEdge(String from, String to, String type, double weight)
      Adds or replaces an edge with specified weight. Automatically adds nodes if they don't exist.
      Parameters:
      from - source agent ID
      to - target agent ID
      type - interaction type
      weight - edge weight

    • incrementEdge

      public void incrementEdge(String from, String to, String type)
      Increments the weight of an existing edge by 1.0, or creates it with weight 1.0.
      Parameters:
      from - source agent ID
      to - target agent ID
      type - interaction type

    • getEdges

      public List<InteractionGraph.Edge> getEdges()
      Gets all edges in the graph.
      Returns:
      list of all edges

    • getEdgesFrom

      public List<InteractionGraph.Edge> getEdgesFrom(String agentId)
      Gets all edges originating from a specific agent.
      Parameters:
      agentId - source agent ID
      Returns:
      list of outgoing edges

    • getEdgesTo

      public List<InteractionGraph.Edge> getEdgesTo(String agentId)
      Gets all edges targeting a specific agent.
      Parameters:
      agentId - target agent ID
      Returns:
      list of incoming edges

    • getEdge

      public Optional<InteractionGraph.Edge> getEdge(String from, String to, String type)
      Gets a specific edge between two agents of a given type.
      Parameters:
      from - source agent ID
      to - target agent ID
      type - interaction type
      Returns:
      the edge if found

    • edgeCount

      public int edgeCount()
      Returns the total number of edges in the graph.
      Returns:
      edge count

    • getInDegree

      public double getInDegree(String agentId)
      Gets the in-degree of an agent (sum of incoming edge weights).
      Parameters:
      agentId - agent identifier
      Returns:
      sum of incoming edge weights, 0.0 if no incoming edges

    • getOutDegree

      public double getOutDegree(String agentId)
      Gets the out-degree of an agent (sum of outgoing edge weights).
      Parameters:
      agentId - agent identifier
      Returns:
      sum of outgoing edge weights, 0.0 if no outgoing edges

    • getNeighbors

      public Set<String> getNeighbors(String agentId)
      Gets all agents connected to a given agent (both incoming and outgoing).
      Parameters:
      agentId - agent identifier
      Returns:
      set of connected agent IDs

    • toDotFormat

      public String toDotFormat()
      Exports the graph in Graphviz DOT format.

      Edge pen widths are scaled relative to the maximum edge weight.

      Returns:
      DOT format string

    • toMap

      public Map<String,Object> toMap()
      Exports the graph as a JSON-friendly map representation.
      Returns:
      map with "nodes" and "edges" keys

    • clear

      public void clear()
      Removes all nodes and edges from the graph.