scml.oneshot.agent

Implements the base classes for all agents that can join a SCML2020OneShotWorld.

Remarks:

• You can access all of the negotiators associated with the agent using self.negotiators which is a dictionary mapping the negotiator_id to a tuple of two values: The SAONegotiator object and a key-value context dictionary. In 2021, the context will always be empty.

• The negotiator_id associated with a negotiation with some partner will be the same as the agent ID of that partner. This means that all negotiators engaged with some partner over all simulation steps will have the same ID which is useful if you are keeping information about past negotiations and partner behavior.

Module Contents

Classes

OneShotAgent	Base class for all agents in the One-Shot game.
OneShotSyncAgent	An agent that automatically accumulate offers from opponents and allows
OneShotSingleAgreementAgent	A synchronized agent that tries to get no more than one agreement.
EndingNegotiator	Base class for all SAO negotiators.
OneShotIndNegotiatorsAgent	A one-shot agent that deligates all of its decisions to a set of independent

class scml.oneshot.agent.OneShotAgent(owner=None, ufun: scml.oneshot.OneShotUFun | None = None, name=None)

Bases: negmas.SAOController, negmas.Entity, abc.ABC

Base class for all agents in the One-Shot game.

Remarks:

• You can access all of the negotiators associated with the agent using self.negotiators which is a dictionary mapping the negotiator_id to a tuple of two values: The SAONegotiator object and a key-value context dictionary. In 2021, the context will always be empty.

• The negotiator_id associated with a negotiation with some partner will be the same as the agent ID of that partner. This means that all negotiators engaged with some partner over all simulation steps will have the same ID which is useful if you are keeping information about past negotiations and partner behavior.

property awi: scml.oneshot.OneShotAWI

Returns a OneShotAWI object for accessing the simulation.

property running_negotiations: list[negmas.situated.RunningNegotiationInfo]

The negotiations currently requested by the agent.

Returns:

A list of negotiation information objects (RunningNegotiationInfo)

property unsigned_contracts: list[negmas.Contract]

All contracts that are not yet signed.

property internal_state: dict[str, Any]

Returns the internal state of the agent for debugging purposes.

Remarks:

• In your agent, you can add any key-value pair to this dict and then use agent_log_* methods to log this information at any point.

init()

Called once after the AWI is set.

Remarks:

• Use this for any proactive initialization code.

make_ufun(add_exogenous=False)

Creates a utility function for the agent.

Parameters:

add_exogenous – If True then the exogenous contracts of the agent will be automatically added whenever the ufun is evaluated for any set of contracts, offers or otherwise.

Remarks:

• You can always as assume that self.ufun returns the ufun for your. You will not need to directly use this method in most cases.

before_step()

Called at the beginning of every step.

Remarks:

• Use this for any proactive code that needs to be done every simulation step.

step()

Called at the end of every step.

Remarks:

• Use this for any proactive code that needs to be done every simulation step.

connect_to_oneshot_adapter(owner)

Connects the agent to its adapter (used internally)

connect_to_2021_adapter(owner)

Connects the agent to its adapter (used internally)

abstract propose(negotiator_id: str, state: negmas.SAOState) → negmas.Outcome | None

Proposes an offer to one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

an outcome to offer.

respond(negotiator_id: str, state: negmas.SAOState, source=None) → negmas.ResponseType

Responds to an offer from one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

A response type which can either be reject, accept, or end negotiation.

Remarks:

default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise

on_negotiation_failure(partners: list[str], annotation: dict[str, Any], mechanism: negmas.sao.SAONMI, state: negmas.SAOState) → None

Called whenever a negotiation ends without agreement.

Parameters:

• partners – List of the partner IDs consisting from self and the opponent.

• annotation – The annotation of the negotiation including the seller ID, buyer ID, and the product.

• mechanism – The NegotiatorMechanismInterface instance containing all information about the negotiation.

• state – The final state of the negotiation of the type SAOState including the agreement if any.

on_negotiation_success(contract: negmas.Contract, mechanism: negmas.sao.SAONMI) → None

Called whenever a negotiation ends with agreement.

Parameters:

• contract – The Contract agreed upon.

• mechanism – The NegotiatorMechanismInterface instance containing all information about the negotiation that led to the Contract if any.

sign_all_contracts(contracts: list[negmas.Contract]) → list[str | None]

Signs all contracts (used internally)

on_contract_executed(contract) → None

on_contract_breached(contract, breaches, resolution) → None

get_negotiator(partner_id: str) → negmas.sao.SAONegotiator

Returns the negotiator corresponding to the given partner ID.

Remarks:

• Note that the negotiator ID and the partner ID are always the same.

get_ami(partner_id: str) → negmas.sao.SAONMI

Returns the SAONMI (Agent Mechanism Interface) connecting the agent to the negotiation mechanism for the given partner.

get_nmi(partner_id: str) → negmas.sao.SAONMI

Returns the SAONMI (Agent Mechanism Interface) connecting the agent to the negotiation mechanism for the given partner.

class scml.oneshot.agent.OneShotSyncAgent(*args, **kwargs)

Bases: negmas.SAOSyncController, OneShotAgent, abc.ABC

An agent that automatically accumulate offers from opponents and allows you to control all negotiations centrally in the counter_all method.

abstract counter_all(offers: dict[str, negmas.Outcome | None], states: dict[str, negmas.SAOState]) → dict[str, negmas.SAOResponse]

Calculate a response to all offers from all negotiators (negotiator ID is the key).

Parameters:

• offers – Maps negotiator IDs to offers

• states – Maps negotiator IDs to offers AT the time the offers were made.

Returns:

A dictionary mapping negotiator ID to an SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.

Remarks:

• The response type CANNOT be WAIT.

• If the system determines that a loop is formed, the agent may

receive this call for a subset of negotiations not all of them.

abstract first_proposals() → dict[str, negmas.Outcome | None]

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

Returns:

A dictionary mapping each negotiator (in self.negotiators dict) to an outcome to be used as the first proposal if the agent is to start a negotiation.

sign_all_contracts(contracts: list[negmas.Contract]) → list[str | None]

Signs all contracts (used internally)

class scml.oneshot.agent.OneShotSingleAgreementAgent(*args, strict: bool = False, **kwargs)

Bases: negmas.SAOSingleAgreementController, OneShotSyncAgent

A synchronized agent that tries to get no more than one agreement.

This controller manages a set of negotiations from which only a single one – at most – is likely to result in an agreement. To guarantee 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

abstract is_acceptable(offer: negmas.Outcome, source: str, state: negmas.SAOState) → bool

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 best_offer(offers: dict[str, negmas.Outcome]) → str | None

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.

abstract is_better(a: negmas.Outcome | None, b: negmas.Outcome | None, negotiator: str, state: negmas.SAOState) → bool

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)

class scml.oneshot.agent.EndingNegotiator(preferences: negmas.preferences.preferences.Preferences | None = None, ufun: negmas.preferences.base_ufun.BaseUtilityFunction | None = None, name: str | None = None, parent: negmas.negotiators.Controller | None = None, owner: negmas.situated.Agent | None = None, id: str | None = None, type_name: str | None = None, can_propose: bool = True, **kwargs)

Bases: negmas.sao.SAONegotiator, negmas.ControlledNegotiator

Base class for all SAO negotiators.

Parameters:

• name – Negotiator name

• parent – Parent controller if any

• preferences – The preferences of the negotiator

• ufun – The utility function of the negotiator (overrides preferences if given)

• owner – The Agent that owns the negotiator.

Remarks:

• The only method that must be implemented by any SAONegotiator is propose.

• The default respond method, accepts offers with a utility value no less than whatever propose returns with the same mechanism state.

propose(state)

Propose an offer or None to refuse.

Parameters:

state – GBState giving current state of the negotiation.

Returns:

The outcome being proposed or None to refuse to propose

Remarks:

• This function guarantees that no agents can propose something with a utility value

respond(state, source=None)

Called to respond to an offer. This is the method that should be overriden to provide an acceptance strategy.

Parameters:

• state – a SAOState giving current state of the negotiation.

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

Returns:

The response to the offer

Return type:

ResponseType

Remarks:

• The default implementation never ends the negotiation

• The default implementation asks the negotiator to propose`() and accepts the `offer if its utility was at least as good as the offer that it would have proposed (and above the reserved value).

• The current offer to respond to can be accessed through state.current_offer

class scml.oneshot.agent.OneShotIndNegotiatorsAgent(*args, default_negotiator_type='negmas.sao.AspirationNegotiator', default_negotiator_params=None, normalize_ufuns=False, set_reservation=False, **kwargs)

Bases: OneShotAgent

A one-shot agent that deligates all of its decisions to a set of independent negotiators (one per partner per day).

Parameters:

• default_negotiator_type – An SAONegotiator descendent to be used for creating all negotiators. It can be passed either as a class object or a string with the full class name (e.g. “negmas.sao.AspirationNegotiator”).

• default_negotiator_type – A dict specifying the paratmers used to create negotiators.

• normalize_ufuns – If true, all utility functions will be normalized to have a maximum of 1.0 (the minimum value may be negative).

• set_reservation – If given, the reserved value of all ufuns will be guaranteed to be between the minimum and maximum of the ufun. This is needed to avoid failures of some GeniusNegotiators.

Remarks:

• To use this class, you need to override generate_ufuns. If you want to change the negotiator type used depending on the partner, you can also override generate_negotiator.

• If you are using a GeniusNegotiator you must guarantee the following:

  • All ufuns are of the type LinearAdditiveUtilityFunction.

  • All ufuns are normalized with a maximum value of 1.0. You can use normalize_ufuns=True to gruarantee that.

  • All ufuns have a finite reserved value and at least one outcome is

  above it. You can guarantee that by using set_reservation=True.

  • All weights of the LinearAdditiveUtilityFunction must be between zero and one and the weights must sum to one.

abstract generate_ufuns() → dict[str, negmas.preferences.UtilityFunction]

Returns a utility function for each partner. All ufuns MUST be of type LinearAdditiveUtilityFunction if a genius negotiator is used.

generate_negotiator(partner_id: str) → negmas.sao.SAONegotiator

Returns a negotiator to be used with some partner.

Remarks:

The default implementation will use the default_negotiator_type and default_negotiator_params.

_urange(u: negmas.preferences.UtilityFunction, issues: tuple[negmas.Issue, Ellipsis])

_unorm(u: negmas.preferences.UtilityFunction, mn, mx)

_get_ufuns()

Internal method that makes sure the reservation value is set to a meaningful value and that the ufun is normalized if needed

init()

Called once after the AWI is set.

Remarks:

• Use this for any proactive initialization code.

step()

Called at the end of every step.

Remarks:

• Use this for any proactive code that needs to be done every simulation step.

make_negotiator(negotiator_type=None, name: str | None = None, **kwargs) → negmas.ControlledSAONegotiator

Creates a negotiator but does not add it to the controller. Call add_negotiator to add it.

Parameters:

• negotiator_type – Type of the negotiator to be created.

• name – negotiator name

• **kwargs – any key-value pairs to be passed to the negotiator constructor

Returns:

The negotiator to be controlled. None for failure

Remarks:

If you would like not to negotiate, just return EndingNegotiator() instead of None. The value None should only be returned if an exception is to be thrown.

propose(negotiator_id, state)

Proposes an offer to one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

an outcome to offer.