Feature: Implement a Generalized Exchange and Negotiation System

[bordumb]

Feature: Implement a Generalized Exchange and Negotiation System

Labels: feature, epic, research, social-science, economics, agent-engine

Opened: 2025-07-14

---

1. Overview & Motivation

To elevate ARLA into a truly generalizable platform for computational social science, we need to implement a foundational primitive for all forms of social and economic interaction: exchange. This moves beyond single-purpose systems (like a hardcoded "trade" or "barter" system) to a powerful, abstract ExchangeSystem that can model a vast range of phenomena, from simple resource trades to complex, multi-step negotiations and even the exchange of intangible social goods.

This system will be the bedrock for future research into:

• Economics: Barter, fixed-price markets, and auctions.
• Game Theory: The ultimatum game, prisoner's dilemma, and recursive negotiations.
• Social Psychology: The dynamics of reciprocity, trust, and social capital.

2. Detailed Architectural Plan

This new system will be implemented within the agent-engine to be reusable across all simulations.

New Core Component (agent-core/components.py)

• NegotiationComponent(Component): Attached to agents to track the state of their ongoing exchanges.

  • active_negotiations: Dict[str, Negotiation] (A dictionary mapping a unique negotiation_id to a state object).

• Negotiation (dataclass): A simple data structure to hold the state of a single negotiation.

  • negotiation_id: str
  • initiator_id: str
  • receiver_id: str
  • offer: Dict[str, Any] (What the initiator is giving up, e.g., {"resource.wood": 10}). The key should be a string that can be resolved to a specific component and attribute.
  • ask: Dict[str, Any] (What the initiator wants in return, e.g., {"resource.stone": 5}).
  • status: str (An enum: PENDING, COUNTERED, ACCEPTED, REJECTED, COMPLETED, FAILED, TIMED_OUT).
  • history: List[Tuple[str, Dict]] (A log of offers and counter-offers).
  • last_update_tick: int (To track for timeouts).

New Core Actions (agent-core/actions/)

• ProposeExchangeAction(ActionInterface): The primary action to start any transaction.
  • Params: {"target_agent_id": str, "offer": Dict, "ask": Dict}.
• RespondToOfferAction(ActionInterface): Used to continue a negotiation.
  • Params: {"negotiation_id": str, "response": str, "counter_offer": Optional[Dict], "counter_ask": Optional[Dict]}. The response can be accept, reject, or counter.

New Core System (agent-engine/systems/)

• ExchangeSystem(System): The engine that orchestrates all negotiations and transactions.
  1. Listens for ProposeExchangeAction and RespondToOfferAction events.
  2. Initiates: When an agent proposes an exchange, the system creates a Negotiation object, validates that the initiator actually possesses the offered goods, and adds the Negotiation to the NegotiationComponent of both participating agents. It then notifies the receiving agent.
  3. Mediates: It processes responses. If an offer is countered, it validates the counter-offer and updates the Negotiation state, notifying the original initiator.
  4. Executes: If an offer is accepted, the ExchangeSystem performs the actual transfer. This is the critical part: it will modify the components of both agents (e.g., deduct from one agent's InventoryComponent and add to the other's). For abstract goods, it might modify a RelationalSchema in the SocialMemoryComponent.
  5. Terminates: It cleans up the Negotiation object from the components once the exchange is completed, rejected, failed, or timed_out.

3. Edge Cases and Considerations

A robust ExchangeSystem must handle numerous edge cases:

• Transaction Atomicity: What if Agent A agrees to give wood for stone from Agent B, but by the time the deal is executed, Agent B has spent their stone? The system must perform a final validation check immediately before the transfer. If either party cannot fulfill their side, the Negotiation status must be set to FAILED, and both parties should be notified. No partial transfers should occur.
• Asynchronous Responses & Timeouts: Agents may not respond immediately. The ExchangeSystem's update method should periodically scan all active negotiations. If current_tick - last_update_tick exceeds a configurable threshold (e.g., negotiation_timeout_ticks), the negotiation's status should be set to TIMED_OUT and terminated.
• Resource/State Validation: The system must have a robust way to parse the offer and ask dictionaries (e.g., "resource.wood") and map them to the correct component (InventoryComponent) and attribute (wood) on the agent entity. It must check for both existence and sufficient quantity before initiating or executing a trade.
• Intangible Goods: For exchanges involving abstract concepts (e.g., offer: "information", ask: "increase_trust"), the ExchangeSystem will need a way to apply these effects. This could be done by publishing a generic apply_social_effect event that other systems (like the IdentitySystem or SocialMemorySystem) can listen for. The event payload would include the target agent and the effect to be applied (e.g., {"effect": "increase_trust", "value": 0.5}).
• Concurrent Offers: What happens if Agent A makes an offer to Agent B, and while B is deciding, Agent C makes a better offer? The current design handles this naturally. Agent B will have two separate Negotiation objects in its NegotiationComponent. Its decision-making logic will have to choose which RespondToOfferAction to execute. It can accept one and reject (or ignore) the other.

4. Phased Implementation Plan

1. Phase 1: Core Data Structures & Actions

   • Implement NegotiationComponent and the Negotiation dataclass in agent-core.
   • Implement ProposeExchangeAction and RespondToOfferAction in agent-core.

2. Phase 2: "Happy Path" System Logic

   • Implement the ExchangeSystem in agent-engine.
   • Implement the logic to handle ProposeExchangeAction: create the Negotiation object and notify the receiver.
   • Implement the logic to handle an accept response from RespondToOfferAction, including the final validation and execution of the transfer for simple numerical resources.

3. Phase 3: Edge Case and Negotiation Logic

   • Add logic to handle reject and counter responses.
   • Implement the timeout mechanism in the ExchangeSystem's update method.
   • Implement the atomic transaction logic to prevent partial trades.

4. Phase 4: Integration and Testing

   • Integrate the new components and actions into the soul-sim ScenarioLoader for a subset of agents.
   • Write unit tests for the ExchangeSystem covering all edge cases.
   • Run a test simulation in soul-sim where agents can successfully barter for different types of resources.

5. Updated Definition of Done

• All new components and actions are defined and implemented in agent-core.
• The ExchangeSystem is implemented in agent-engine and handles the full lifecycle of a negotiation (propose, accept, reject, counter, timeout, fail, complete).
• The system can successfully mediate a simple resource-for-resource trade between two agents in the soul-sim environment.
• Unit tests for the ExchangeSystem exist and provide high coverage, including for all identified edge cases.
• The system is designed with a clear path to supporting abstract/social exchanges.

[bordumb]

Related to #21