SAOSingleAgreementController

class negmas.sao.SAOSingleAgreementController(*args, strict=False, **kwargs)[source]

Bases: negmas.sao.SAOSyncController, abc.ABC

A synchronized controller that tries to get no more than one agreeement.

This controller manages a set of negotiations from which only a single one – at most – is likely to result in an agreement. An example of a case in which it is useful is an agent negotiating to buy a car from multiple suppliers. It needs a single car at most but it wants the best one from all of those suppliers. To guarentee a single agreement, pass strict=True

The general algorithm for this controller is something like this:

  • Receive offers from all partners.

  • Find the best offer among them by calling the abstract best_offer method.

  • Check if this best offer is acceptable using the abstract is_acceptable method.

    • If the best offer is acceptable, accept it and end all other negotiations.

    • If the best offer is still not acceptable, then all offers are rejected and with the partner who sent it receiving the result of best_outcome while the rest of the partners receive the result of make_outcome.

  • The default behavior of best_outcome is to return the outcome with maximum utility.

  • The default behavior of make_outcome is to return the best offer received in this round if it is valid for the respective negotiation and the result of best_outcome otherwise.

Parameters

strict – If True the controller is guaranteed to get a single agreement but it will have to send no-response repeatedly so there is a higher chance of never getting an agreement when two of those controllers negotiate with each other

Methods Summary

after_join(negotiator_id, ami, state, *[, …])

Called by children negotiators after joining a negotiation to inform the controller

best_offer(offers)

Return the ID of the negotiator with the best offer

best_outcome(negotiator[, state])

The best outcome for the negotiation negotiator engages in given the state .

counter_all(offers, states)

Counters all responses

first_proposals()

Gets a set of proposals to use for initializing the negotiation.

is_acceptable(offer, source, state)

Should decide if the given offer is acceptable

is_better(a, b, negotiator, state)

Compares two outcomes of the same negotiation

make_offer(negotiator, state, best_offer, …)

Generate an offer for the given partner

on_negotiation_end(negotiator_id, state)

A call back called at each negotiation end

response_to_best_offer(negotiator, state, offer)

Return a response to the partner from which the best current offer was received

Methods Documentation

after_join(negotiator_id, ami, state, *, ufun=None, role='agent')[source]

Called by children negotiators after joining a negotiation to inform the controller

Parameters
abstract best_offer(offers: Dict[str, Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]])Optional[str][source]

Return the ID of the negotiator with the best offer

Parameters

offers – A mapping from negotiator ID to the offer it received

Returns

The ID of the negotiator with best offer. Ties should be broken. Return None only if there is no way to calculate the best offer.

best_outcome(negotiator: str, state: Optional[negmas.sao.SAOState] = None)Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]][source]

The best outcome for the negotiation negotiator engages in given the state .

Parameters
  • negotiator – The negotiator for which the best outcome is to be found

  • state – If given, the state of the negotiation. If None, should return the absolute best outcome

Returns

The outcome with maximum utility.

Remarks:

  • The default implementation, just returns the best outcome for this negotiation without considering the state or returns None if it is not possible to find this best outcome.

  • If the negotiator defines a ufun, it is used otherwise the ufun defined for the controller if used (if any)

counter_all(offers: Dict[str, Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], states: Dict[str, negmas.sao.SAOState])Dict[str, negmas.sao.SAOResponse][source]

Counters all responses

Parameters
  • offers – A dictionary mapping partner ID to offer

  • states – A dictionary mapping partner ID to mechanism state

Returns

A dictionary mapping partner ID to a response

Remarks:

The agent will counter all offers by either ending all negotiations except one which is accepted or by rejecting all offers and countering them using the make_offer method.

first_proposals()Dict[str, Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]][source]

Gets a set of proposals to use for initializing the negotiation.

abstract is_acceptable(offer: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], source: str, state: negmas.sao.SAOState)bool[source]

Should decide if the given offer is acceptable

Parameters
  • offer – The offer being tested

  • source – The ID of the negotiator that received this offer

  • state – The state of the negotiation handled by that negotiator

Remarks:
  • If True is returned, this offer will be accepted and all other negotiations will be ended.

abstract is_better(a: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], b: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], negotiator: str, state: negmas.sao.SAOState)[source]

Compares two outcomes of the same negotiation

Parameters
  • a – “Outcome”

  • b – “Outcome”

  • negotiator – The negotiator for which the comparison is to be made

  • state – Current state of the negotiation

Returns

True if utility(a) > utility(b)

make_offer(negotiator: str, state: negmas.sao.SAOState, best_offer: Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], best_from: Optional[str])Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]][source]

Generate an offer for the given partner

Parameters
  • negotiator – The ID of the negotiator for who an offer is to be made.

  • state – The mechanism state of this partner

  • best_offer – The best offer received in this round. None means that no known best offers.

  • best_from – The ID of the negotiator that received the best offer

Returns

The outcome to be offered to negotiator (None means no-offer)

Remarks:

Default behavior is to offer everyone best_offer if available otherwise, it returns no offers (None). The best_from negotiator will be sending the result of best_outcome.

on_negotiation_end(negotiator_id: str, state: negmas.common.MechanismState)None[source]

A call back called at each negotiation end

Parameters
  • negotiator_id – The negotiator ID

  • stateMechanismState or one of its descendants giving the state at which the negotiation ended.

response_to_best_offer(negotiator: str, state: negmas.sao.SAOState, offer: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]])Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]][source]

Return a response to the partner from which the best current offer was received

Parameters
  • negotiator – The negotiator from which the best offer was received

  • state – The state of the corresponding negotiation

  • offer – The best offer received at this round.

Returns

The offer to be sent back to negotiator