Package com.tnsai.coordination.groups.hierarchy

Interface Hierarchy

All Superinterfaces:
com.tnsai.agents.groups.AgentGroup
All Known Implementing Classes:
DefaultHierarchy
public interface Hierarchy extends com.tnsai.agents.groups.AgentGroup
A tree-based organization structure with parent-child relationships.

Hierarchy extends AgentGroup with delegation chains, reporting lines, and hierarchical task flow. Tasks can be delegated down the hierarchy and escalated up when needed.

Key Features

  • Delegation: Tasks flow down from supervisor to subordinates
  • Escalation: Issues can be escalated up the chain
  • Reporting Lines: Clear supervisor-subordinate relationships
  • Level-based routing: Tasks can target specific hierarchy levels

Usage Example


 Hierarchy hierarchy = Hierarchy.builder()
     .name("Engineering Org")
     .root(cto)
     .member(cto, teamLead1)
     .member(cto, teamLead2)
     .member(teamLead1, dev1)
     .member(teamLead1, dev2)
     .build();

 hierarchy.start();
 HierarchyResult result = hierarchy.delegate("Design new API", 2);
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static HierarchyBuilder
    builder()
    Creates a new Hierarchy builder.
    HierarchyResult
    delegate(String task, int targetLevel)
    Delegates a task down to a specific level in the hierarchy.
    HierarchyResult
    escalate(String task, String fromAgentId)
    Escalates a task up from a given agent to their supervisor.
    DelegationChain
    getDelegationChain()
    Returns the delegation chain history.
    int
    getLevel(String agentId)
    Returns the depth level of an agent in the hierarchy.
    List<com.tnsai.agents.Agent>
    getReportingChain(String agentId)
    Returns the full reporting chain from root to the given agent.
    List<ReportingLine>
    getReportingLines()
    Returns all reporting lines in the hierarchy.
    Optional<com.tnsai.agents.Agent>
    getRoot()
    Returns the root agent of the hierarchy.
    List<com.tnsai.agents.Agent>
    getSubordinates(String agentId)
    Returns the direct subordinates of a given agent.
    Optional<com.tnsai.agents.Agent>
    getSupervisor(String agentId)
    Returns the supervisor of a given agent.
    void
    setReportingLine(String parentId, String childId)
    Sets a parent-child relationship.

    Methods inherited from interface com.tnsai.agents.groups.AgentGroup

    addLifecycleListener, addMember, addMembershipListener, assignTask, broadcast, broadcast, dissolve, electLeader, electLeader, findMembers, getDescription, getEventBus, getId, getLeader, getLifecycle, getMember, getMemberCount, getMembers, getMembershipManager, getMetrics, getName, getPolicy, hasMember, isActive, isDissolved, removeLifecycleListener, removeMember, removeMembershipListener, scatter, scatter, scatterAsync, setPolicy, start, stop, stopNow

  • Method Details

    • getRoot

      Optional<com.tnsai.agents.Agent> getRoot()
      Returns the root agent of the hierarchy.
      Returns:
      root agent

    • getSupervisor

      Optional<com.tnsai.agents.Agent> getSupervisor(String agentId)
      Returns the supervisor of a given agent.
      Parameters:
      agentId - agent ID
      Returns:
      supervisor, or empty if agent is root or not found

    • getSubordinates

      List<com.tnsai.agents.Agent> getSubordinates(String agentId)
      Returns the direct subordinates of a given agent.
      Parameters:
      agentId - agent ID
      Returns:
      list of subordinate agents

    • getReportingChain

      List<com.tnsai.agents.Agent> getReportingChain(String agentId)
      Returns the full reporting chain from root to the given agent.
      Parameters:
      agentId - agent ID
      Returns:
      list of agents from root to the target (inclusive)

    • getReportingLines

      List<ReportingLine> getReportingLines()
      Returns all reporting lines in the hierarchy.
      Returns:
      list of reporting lines

    • getLevel

      int getLevel(String agentId)
      Returns the depth level of an agent in the hierarchy. Root is level 0.
      Parameters:
      agentId - agent ID
      Returns:
      level, or -1 if not found

    • setReportingLine

      void setReportingLine(String parentId, String childId)
      Sets a parent-child relationship.
      Parameters:
      parentId - parent agent ID
      childId - child agent ID
      Throws:
      IllegalArgumentException - if either agent is not a member

    • delegate

      HierarchyResult delegate(String task, int targetLevel)
      Delegates a task down to a specific level in the hierarchy.
      Parameters:
      task - task description
      targetLevel - target hierarchy level (0=root)
      Returns:
      delegation result

    • escalate

      HierarchyResult escalate(String task, String fromAgentId)
      Escalates a task up from a given agent to their supervisor.
      Parameters:
      task - task description
      fromAgentId - agent escalating the task
      Returns:
      escalation result

    • getDelegationChain

      DelegationChain getDelegationChain()
      Returns the delegation chain history.
      Returns:
      delegation chain

    • builder

      static HierarchyBuilder builder()
      Creates a new Hierarchy builder.
      Returns:
      builder