Package com.tnsai.coordination.groups.coalition

Interface Coalition

All Superinterfaces:
com.tnsai.agents.groups.AgentGroup
All Known Implementing Classes:
DefaultCoalition
public interface Coalition extends com.tnsai.agents.groups.AgentGroup
Coalition is a goal-oriented temporary alliance with reward distribution.

Unlike Teams (persistent) or Swarms (emergent), Coalitions form dynamically around specific goals and dissolve after completion. Members negotiate participation and share rewards based on contribution.

Key Characteristics

  • Goal-Oriented - Forms around specific objectives
  • Temporary - Dissolves after goal achieved
  • Negotiated - Members negotiate participation terms
  • Reward Sharing - Benefits distributed based on contribution

Usage Example


 Coalition coalition = Coalition.builder()
     .goal("Complete complex analysis")
     .formation(CoalitionFormation.VOLUNTARY)
     .rewardDistribution(RewardDistribution.SHAPLEY)
     .minMembers(3)
     .add(agent1, agent2, agent3)
     .build();

 // Negotiate and form
 boolean formed = coalition.negotiate();

 if (formed) {
     CoalitionResult result = coalition.achieve();
     Map<String, Double> rewards = result.rewards();
 }
See Also:

  • Method Details

    • getGoal

      String getGoal()
      Gets the coalition goal.
      Returns:
      goal description

    • getFormation

      CoalitionFormation getFormation()
      Gets the formation strategy.
      Returns:
      formation strategy

    • getRewardDistribution

      RewardDistribution getRewardDistribution()
      Gets the reward distribution strategy.
      Returns:
      reward distribution

    • getCoalitionValue

      double getCoalitionValue()
      Gets the current coalition value (total reward pool).
      Returns:
      coalition value

    • setCoalitionValue

      void setCoalitionValue(double value)
      Sets the coalition value.
      Parameters:
      value - new value

    • getContribution

      double getContribution(String agentId)
      Gets an agent's contribution score.
      Parameters:
      agentId - agent ID
      Returns:
      contribution score (0.0 to 1.0)

    • recordContribution

      void recordContribution(String agentId, double contribution)
      Records a contribution from an agent.
      Parameters:
      agentId - agent ID
      contribution - contribution amount

    • getAllContributions

      Map<String,Double> getAllContributions()
      Gets all member contributions.
      Returns:
      map of agent IDs to contributions

    • getEstimatedReward

      double getEstimatedReward(String agentId)
      Gets estimated reward for an agent.
      Parameters:
      agentId - agent ID
      Returns:
      estimated reward

    • negotiate

      boolean negotiate()
      Initiates coalition negotiation.

      During negotiation:

      • Potential members evaluate the goal
      • Members commit or decline participation
      • Coalition forms if minimum threshold met
      Returns:
      true if coalition formed successfully

    • negotiateAsync

      CompletableFuture<Boolean> negotiateAsync()
      Async negotiation.
      Returns:
      future with formation result

    • getNegotiationStatus

      Coalition.NegotiationStatus getNegotiationStatus()
      Gets negotiation status.
      Returns:
      negotiation status

    • getCommittedMembers

      List<String> getCommittedMembers()
      Gets list of committed members.
      Returns:
      committed member IDs

    • getDeclinedMembers

      List<String> getDeclinedMembers()
      Gets list of members who declined.
      Returns:
      declined member IDs

    • hasCommitted

      boolean hasCommitted(String agentId)
      Checks if an agent has committed.
      Parameters:
      agentId - agent ID
      Returns:
      true if committed

    • achieve

      CoalitionResult achieve()
      Attempts to achieve the coalition goal.
      Returns:
      result with outcomes and rewards

    • achieve

      CoalitionResult achieve(Map<String,Object> context)
      Achieves with additional context.
      Parameters:
      context - additional context
      Returns:
      result

    • achieveAsync

      CompletableFuture<CoalitionResult> achieveAsync()
      Async goal achievement.
      Returns:
      future result

    • isGoalAchieved

      boolean isGoalAchieved()
      Checks if goal has been achieved.
      Returns:
      true if achieved

    • distributeRewards

      Map<String,Double> distributeRewards(double totalValue)
      Calculates and distributes rewards to members.
      Parameters:
      totalValue - total value to distribute
      Returns:
      map of agent IDs to rewards

    • getRewardHistory

      List<Coalition.RewardRecord> getRewardHistory()
      Gets reward history.
      Returns:
      list of reward distributions

    • dissolveCoalition

      void dissolveCoalition(boolean goalAchieved)
      Dissolves the coalition (with or without goal achieved).
      Parameters:
      goalAchieved - whether goal was achieved

    • isDissolved

      boolean isDissolved()
      Checks if coalition has dissolved.
      Specified by:
      isDissolved in interface com.tnsai.agents.groups.AgentGroup
      Returns:
      true if dissolved

    • builder

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