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.

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. Implemented by implementing propose() and respond() methods.
`OneShotIndNegotiatorsAgent`	A one-shot agent that deligates all of its decisions to a set of independent

Module Contents

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

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.

_awi = None[source]

_owner = None[source]

property awi: scml.oneshot.OneShotAWI[source]: Returns a OneShotAWI object for accessing the simulation.

property running_negotiations: list[negmas.situated.RunningNegotiationInfo][source]

The negotiations currently requested by the agent.

Returns:: A list of negotiation information objects (RunningNegotiationInfo)

property unsigned_contracts: list[negmas.Contract][source]: All contracts that are not yet signed.

init()[source]

Called once after the AWI is set.

Remarks:

Use this for any proactive initialization code.

make_ufun(add_exogenous=False)[source]

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()[source]

Called at the beginning of every step.

Remarks:

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

step()[source]

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)[source]: Connects the agent to its adapter (used internally)

connect_to_2021_adapter(owner)[source]: Connects the agent to its adapter (used internally)

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

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[source]

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

property internal_state: dict[str, Any][source]

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.

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

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[source]

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][source]: Signs all contracts (used internally)

on_contract_executed(contract) → None[source]

on_contract_breached(contract, breaches, resolution) → None[source]

get_negotiator(partner_id: str) → negmas.sao.SAONegotiator[source]

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[source]: 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[source]: Returns the SAONMI (Agent Mechanism Interface) connecting the agent to the negotiation mechanism for the given partner.

class scml.oneshot.agent.OneShotSyncAgent(*args, **kwargs)[source]

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][source]

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][source]

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][source]: Signs all contracts (used internally)

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

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

abstract is_better(a: negmas.Outcome | None, b: negmas.Outcome | None, negotiator: str, state: negmas.SAOState) → bool[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)

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)[source]

Bases: negmas.sao.SAONegotiator, negmas.ControlledNegotiator

Base class for all SAO negotiators. Implemented by implementing propose() and respond() methods.

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.
A default implementation of respond() is provided which simply accepts any offer better than the last offer I gave or the next one I would have given in the current state.

See also

SAOCallNegotiator

propose(state)[source]

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)[source]

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)[source]

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.

_default_negotiator_type = 'negmas.sao.AspirationNegotiator'[source]

_default_negotiator_params[source]

_ufuns[source]

_normalize = False[source]

_set_reservation = False[source]

abstract generate_ufuns() → dict[str, negmas.preferences.UtilityFunction][source]: 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[source]

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])[source]

_unorm(u: negmas.preferences.UtilityFunction, mn, mx)[source]

_get_ufuns()[source]: Internal method that makes sure the reservation value is set to a meaningful value and that the ufun is normalized if needed

init()[source]

Called once after the AWI is set.

Remarks:

Use this for any proactive initialization code.

step()[source]

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[source]

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)[source]

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.