Package com.tnsai.agents.groups

Class GroupRegistry

java.lang.Object
com.tnsai.agents.groups.GroupRegistry
public final class GroupRegistry extends Object
Central registry for managing AgentGroups.

GroupRegistry provides a singleton access point for group management, enabling agents to join, leave, and discover groups dynamically.

Key Features

  • Thread-safe group registration and lookup
  • Auto-creation of groups when needed
  • Agent-to-group membership tracking
  • Global group discovery

Usage Example


 GroupRegistry registry = GroupRegistry.getInstance();

 // Get or create a group
 AgentGroup group = registry.getOrCreate("research-team");

 // Register an existing group
 registry.register(myGroup);

 // Find all groups for an agent
 Set<AgentGroup> agentGroups = registry.getGroupsFor(agent);

Integration with @GroupMember

This registry is used by the agent initialization system to handle the @GroupMember annotation's autoJoin and autoCreateGroups parameters.

Author:
TnsAI Team
See Also:

  • Method Details

    • getInstance

      public static GroupRegistry getInstance()
      Returns the singleton instance.
      Returns:
      the GroupRegistry instance

    • getOrCreate

      public AgentGroup getOrCreate(String groupId)
      Gets an existing group or creates a new one if it doesn't exist.

      The created group uses default configuration. For custom configuration, use AgentGroup.builder() and register(AgentGroup).

      Parameters:
      groupId - the group identifier
      Returns:
      the existing or newly created group

    • get

      public Optional<AgentGroup> get(String groupId)
      Gets a group by ID.
      Parameters:
      groupId - the group identifier
      Returns:
      the group if found

    • exists

      public boolean exists(String groupId)
      Checks if a group exists.
      Parameters:
      groupId - the group identifier
      Returns:
      true if the group exists

    • register

      public void register(AgentGroup group)
      Registers an existing group.

      If a group with the same ID already exists, this method does nothing.

      Parameters:
      group - the group to register
      Throws:
      IllegalArgumentException - if group is null

    • remove

      public boolean remove(String groupId)
      Removes a group from the registry.

      This does not dissolve the group or remove members - it only removes the registry entry.

      Parameters:
      groupId - the group identifier
      Returns:
      true if a group was removed

    • getGroupsFor

      public Set<AgentGroup> getGroupsFor(Agent agent)
      Gets all groups that an agent is a member of.
      Parameters:
      agent - the agent
      Returns:
      set of groups (never null, may be empty)

    • recordMembership

      public void recordMembership(Agent agent, AgentGroup group)
      Records that an agent has joined a group.

      This is called internally when an agent joins a group.

      Parameters:
      agent - the agent
      group - the group

    • removeMembership

      public void removeMembership(Agent agent, AgentGroup group)
      Removes an agent's membership record from a group.

      This is called internally when an agent leaves a group.

      Parameters:
      agent - the agent
      group - the group

    • getAllGroups

      public Set<AgentGroup> getAllGroups()
      Gets all registered groups.
      Returns:
      unmodifiable set of all groups

    • getGroupCount

      public int getGroupCount()
      Gets the number of registered groups.
      Returns:
      group count

    • clear

      public void clear()
      Clears all registrations (for testing).