EndingNegotiator¶

class scml.oneshot.EndingNegotiator(preferences=None, ufun=None, name=None, parent=None, owner=None, id=None, type_name=None, can_propose=True)[source]¶

Bases: SAONegotiator

Attributes Summary

`ami`	rtype: `NegotiatorMechanismInterface`
`capabilities`	Agent capabilities
`crisp_ufun`	Returns the preferences if it is a CrispUtilityFunction else None
`has_cardinal_preferences`	Does the entity has an associated ufun?
`has_preferences`	Does the entity has an associated ufun?
`has_ufun`	Does the entity has an associated ufun?
`id`	The unique ID of this entity
`name`	A convenient name of the entity (intended primarily for printing/logging/debugging).
`nmi`	rtype: `NegotiatorMechanismInterface`
`owner`	Returns the owner agent of the negotiator
`parent`	Returns the parent controller
`preferences`	The utility function attached to that object
`prob_ufun`	Returns the preferences if it is a ProbUtilityFunction else None
`reserved_outcome`	Reserved outcome is the outcome that will be realized by default for this agent.
`reserved_value`	Reserved value is what the entity gets if no agreement is reached in the negotiation.
`short_type_name`	rtype: `str`
`type_name`	rtype: `str`
`ufun`	Returns the preferences if it is a `BaseUtilityFunction` else None
`uuid`	The unique ID of this entity

Methods Summary

`__call__`(state)	Called by `Negotiator.__call__` (which is called by the mechanism) to counter the offer.
`add_capabilities`(capabilities)	Adds named capabilities to the negotiator.
`add_handler`(notification_type, callback)	Adds a notification handler to the list of handlers of the given type.
`before_death`(cntxt)	Called whenever the parent is about to kill this negotiator.
`cancel`([reason])	A method that may be called by a mechanism to make the negotiator cancel whatever it is currently processing.
`checkpoint`(path[, file_name, info, ...])	Saves a checkpoint of the current object at the given path.
`checkpoint_info`(file_name)	Returns the information associated with a dump of the object saved in the given file
`create`(args, *kwargs)	Creates an object and returns a proxy to it.
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`handlers`(notification_type)	Gets the list of handlers registered for some notification type.
`is_acceptable_as_agreement`(outcome)	Whether the given outcome is acceptable as a final agreement of a negotiation.
`isin`(negotiation_id)	Is that agent participating in the given negotiation? Tests if the agent is participating in the given negotiation.
`join`(nmi, state, *[, preferences, ufun, role])	Called by the mechanism when the agent is about to enter a negotiation.
`on_leave`(state)	A call back called after leaving a negotiation.
`on_mechanism_error`(state)	A call back called whenever an error happens in the mechanism.
`on_negotiation_end`(state)	A call back called at each negotiation end
`on_negotiation_start`(state)	A call back called at each negotiation start
`on_notification`(notification, notifier)	Called whenever a notification is received
`on_notification_`(notification, notifier)	Called when a notification is received.
`on_partner_ended`(partner)	Called when a partner ends the negotiation.
`on_partner_proposal`(state, partner_id, offer)	A callback called by the mechanism when a partner proposes something
`on_partner_response`(state, partner_id, ...)	A callback called by the mechanism when a partner responds to some offer
`on_preferences_changed`(changes)	Called to inform the entity that its ufun has changed.
`on_round_end`(state)	A call back called at each negotiation round end
`on_round_start`(state)	A call back called at each negotiation round start
`propose`(state)	Propose an offer or None to refuse.
`propose_`(state)	The method directly called by the mechanism (through `counter` ) to ask for a proposal
`remove_capability`(name)	Removes named capability from the negotiator
`remove_handler`(notification_type, callback)	Removes a notification handler from the list of handlers of the given type.
`respond`(state)	Called to respond to an offer.
`respond_`(state[, source])	The method to be called directly by the mechanism (through `counter` ) to respond to an offer.
`set_preferences`(value[, force])	Sets tha utility function/Preferences.
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)

Attributes Documentation

ami¶

Return type:: NegotiatorMechanismInterface

capabilities¶

Agent capabilities

Return type:: dict[str, Any]

crisp_ufun¶

Returns the preferences if it is a CrispUtilityFunction else None

Return type:: Optional[UtilityFunction]

has_cardinal_preferences¶

Does the entity has an associated ufun?

Return type:: bool

has_preferences¶

Does the entity has an associated ufun?

Return type:: bool

has_ufun¶

Does the entity has an associated ufun?

Return type:: bool

id¶: The unique ID of this entity

name¶: A convenient name of the entity (intended primarily for printing/logging/debugging).

nmi¶

Return type:: NegotiatorMechanismInterface

owner¶

Returns the owner agent of the negotiator

Return type:: Optional[Agent]

parent¶

Returns the parent controller

Return type:: Optional[Controller]

preferences¶

The utility function attached to that object

Return type:: Optional[Preferences]

prob_ufun¶

Returns the preferences if it is a ProbUtilityFunction else None

Return type:: Optional[ProbUtilityFunction]

reserved_outcome¶

Reserved outcome is the outcome that will be realized by default for this agent.

Remarks:

Reserved outcomes are defined for OrdinalPreferences.

See also

reserved_value

Return type:: Optional[tuple]

reserved_value¶

Reserved value is what the entity gets if no agreement is reached in the negotiation.

The reserved value can either be explicity defined for the ufun or it can be the output of the ufun for None outcome.

Return type:: float

short_type_name¶

Return type:: str

type_name¶

Return type:: str

ufun¶

Returns the preferences if it is a BaseUtilityFunction else None

Return type:: Optional[BaseUtilityFunction]

uuid¶: The unique ID of this entity

Methods Documentation

__call__(state)¶

Called by Negotiator.__call__ (which is called by the mechanism) to counter the offer. It just calls respond_ and propose_ as needed.

Parameters:: state (SAOState) – SAOState giving current state of the negotiation.
Returns:: The response to the given offer with a counter offer if the response is REJECT
Return type:: Tuple[ResponseType, Outcome]

Remarks:

The current offer is accessible through state.current_offer

add_capabilities(capabilities)¶

Adds named capabilities to the negotiator.

Parameters:: capabilities (dict) – The capabilities to be added as a dict
Return type:: None
Returns:: None

Remarks:: It is the responsibility of the caller to be really capable of added capabilities.

add_handler(notification_type, callback)¶

Adds a notification handler to the list of handlers of the given type. These handlers will be called in the order in which they are received

Parameters:

notification_type (str) – Notification type as specificed in the type member of the Notification class
callback (Callable[[Notification, str], bool]) – The callback which must receive a Notification object and a string and returns a boolean. If True is returned from one callback, the remaining callbacks will not be called

Returns:

before_death(cntxt)¶

Called whenever the parent is about to kill this negotiator.

It should return False if the negotiator does not want to be killed but the controller can still force-kill it

Return type:: bool

cancel(reason=None)¶

A method that may be called by a mechanism to make the negotiator cancel whatever it is currently processing.

Negotiators can just ignore this message (default behavior) but if there is a way to actually cancel work, it should be implemented here to improve the responsiveness of the negotiator.

Return type:: None

checkpoint(path, file_name=None, info=None, exist_ok=False, single_checkpoint=True, step_attribs=('current_step', '_current_step', '_Entity__current_step', '_step'))¶

Saves a checkpoint of the current object at the given path.

Parameters:

path (PathLike) – Full path to a directory to store the checkpoint
file_name (Optional[str]) – Name of the file to dump into. If not given, a unique name is created
info (Optional[dict[str, Any]]) – Information to save with the checkpoint (must be json serializable)
exist_ok (bool) – If true, override existing dump
single_checkpoint (bool) – If true, keep a single checkpoint for the last step
step_attribs (tuple[str, ...]) – Attributes to represent the time-step of the object. Any of the given attributes will be used in the file name generated if single_checkpoint is False. If single_checkpoint is True, the filename will not contain time-step information

Return type:

Path

Returns:

full path to the file used to save the checkpoint

classmethod checkpoint_info(file_name)¶

Returns the information associated with a dump of the object saved in the given file

Parameters:: file_name (Path | str) – Name of the object

Returns:

Return type:: dict[str, Any]

classmethod create(*args, **kwargs)¶: Creates an object and returns a proxy to it.

classmethod from_checkpoint(file_name, return_info=False)¶

Creates an object from a saved checkpoint

Parameters:

file_name (Path | str) –
return_info (bool) – If True, tbe information saved when the file was dumped are returned

Return type:

NamedObject | tuple[NamedObject, dict[str, Any]]

Returns:

Either the object or the object and dump-info as a dict (if return_info was true)

Remarks:

If info is returned, it is guaranteed to have the following members:

time: Dump time

type: Type of the dumped object

id: ID

name: name

handlers(notification_type)¶

Gets the list of handlers registered for some notification type. This list can be modified in place to change the order of handlers for example. It is NOT a copy.

Return type:: list[Callable[[Notification, str], bool]]

is_acceptable_as_agreement(outcome)¶

Whether the given outcome is acceptable as a final agreement of a negotiation.

The default behavior is to reject only if a reserved value is defined for the agent and is known to be higher than the utility of the outcome.

Return type:: bool

isin(negotiation_id)¶

Is that agent participating in the given negotiation? Tests if the agent is participating in the given negotiation.

Parameters:

negotiation_id (Optional[str]) – The negotiation ID tested. If None, it means ANY negotiation

Returns:

True if participating in the given negotiation (or any: negotiation if it was None)

Return type:

bool

join(nmi, state, *, preferences=None, ufun=None, role='negotiator')¶

Called by the mechanism when the agent is about to enter a negotiation. It can prevent the agent from entering

Parameters:

nmi (AgentMechanismInterface) – The negotiation.
state (MechanismState) – The current state of the negotiation
preferences (Preferences) – The preferences used by the negotiator (see ufun )
ufun (UtilityFunction) – The ufun function to use (overrides preferences )
role (str) – role of the negotiator.

Return type:

bool

Returns:

bool indicating whether or not the agent accepts to enter. If False is returned it will not enter the negotiation

Remarks:

Joining a neogiation will fail in the following conditions:

The negotiator already has preferences and is asked to join with new ones

The negotiator is already in a negotiation

on_leave(state)¶

A call back called after leaving a negotiation.

Parameters:: state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

MUST call the baseclass on_leave using super () if you are going to override this.
The default behavior is to do nothing.
Override this to hook some action

Return type:: None

on_mechanism_error(state)¶

A call back called whenever an error happens in the mechanism. The error and its explanation are accessible in state

Parameters:: state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

The default behavior is to do nothing.
Override this to hook some action

Return type:: None

on_negotiation_end(state)¶

A call back called at each negotiation end

Parameters:: state (MechanismState) – MechanismState or one of its descendants giving the state at which the negotiation ended.

Remarks:

The default behavior is to do nothing.
Override this to hook some action
on_negotiation_start and on_negotiation_end will always be called once for every agent.

Return type:: None

on_negotiation_start(state)¶

A call back called at each negotiation start

Parameters:: state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

You MUST call the super() version of this function either before or after your code when you are overriding it.

on_negotiation_start and on_negotiation_end will always be called once for every agent.

Return type:: None

on_notification(notification, notifier)¶

Called whenever a notification is received

Parameters:

notification (Notification) – The notification
notifier (str) – The notifier entity

Remarks:

The default implementation only responds to end_negotiation by ending the negotiation

on_notification_(notification, notifier)¶

Called when a notification is received. Do NOT directly override this method

Parameters:

notification (Notification) –
notifier (str) –

Returns:

Return type:: bool

on_partner_ended(partner)¶

Called when a partner ends the negotiation.

Note that the negotiator owning this component may never receive this offer. This is only receivd if the mechanism is sending notifications on every offer.

on_partner_proposal(state, partner_id, offer)¶

A callback called by the mechanism when a partner proposes something

Parameters:

state (GBState) – GBState giving the state of the negotiation when the offer was porposed.
partner_id (str) – The ID of the agent who proposed
offer (tuple) – The proposal.

Remarks:

Will only be called if enable_callbacks is set for the mechanism

Return type:: None

on_partner_response(state, partner_id, outcome, response)¶

A callback called by the mechanism when a partner responds to some offer

Parameters:

state (GBState) – GBState giving the state of the negotiation when the partner responded.
partner_id (str) – The ID of the agent who responded
outcome (tuple) – The proposal being responded to.
response (ResponseType) – The response

Remarks:

Will only be called if enable_callbacks is set for the mechanism

Return type:: None

on_preferences_changed(changes)¶

Called to inform the entity that its ufun has changed.

Parameters:: changes (list[PreferencesChange]) – An ordered list of changes that happened.

Remarks:

You MUST call the super() version of this function either before or after your code when you are overriding it.

The most general form of change is PreferencesChange.General which indicates that you cannot trust anything you knew about the ufun anymore

on_round_end(state)¶

A call back called at each negotiation round end

Parameters:: state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

The default behavior is to do nothing.
Override this to hook some action

Return type:: None

on_round_start(state)¶

A call back called at each negotiation round start

Parameters:: state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

The default behavior is to do nothing.
Override this to hook some action.

Return type:: None

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

propose_(state)¶

The method directly called by the mechanism (through counter ) to ask for a proposal

Parameters:: state (SAOState) – The mechanism state
Return type:: Optional[tuple]
Returns:: An outcome to offer or None to refuse to offer

Remarks:

Depending on the SAOMechanism settings, refusing to offer may be interpreted as ending the negotiation
The negotiator will only receive this call if it has the ‘propose’ capability.

remove_capability(name)¶

Removes named capability from the negotiator

Parameters:: capabilities – The capabilities to be added as a dict
Return type:: None
Returns:: None

Remarks:: It is the responsibility of the caller to be really capable of added capabilities.

remove_handler(notification_type, callback)¶

Removes a notification handler from the list of handlers of the given type.

Parameters:

notification_type (str) – Notification type as specificed in the type member of the Notification class
callback (Callable[[Notification, str], bool]) – The callback which must receive a Notification object and a string and returns a boolean. If True is returned from one callback, the remaining callbacks will not be called

Return type:

bool

Returns:

Whether or not the handler was in the list of handlers for this type. In all cases, the handler will not be called after this call (either it was not there or it will be removed).

respond(state)[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

respond_(state, source=None)¶

The method to be called directly by the mechanism (through counter ) to respond to an offer.

Parameters:

state (SAOState) – a SAOState giving current state of the negotiation.
source (Optional[str]) – The ID of the negotiator that gave the offer.

Returns:

The response to the offer. Possible values are:

NO_RESPONSE: refuse to offer. Depending on the mechanism settings this may be interpreted as ending
the negotiation.

ACCEPT_OFFER: Accepting the offer.

REJECT_OFFER: Rejecting the offer. The negotiator will be given the chance to counter this
offer through a call of propose_ later if this was not the last offer to be evaluated by the mechanism.

END_NEGOTIATION: End the negotiation

WAIT: Instructs the mechanism to wait for this negotiator more. It may lead to cycles so use with care.

Return type:

ResponseType

Remarks:

The default implementation never ends the negotiation except if an earler end_negotiation notification is sent to the negotiator
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).

set_preferences(value, force=False)¶

Sets tha utility function/Preferences.

Parameters:

value (Preferences) – The value to set to
force – If true, on_preferecnes_changed() will always be called even if value == self.preferences

Return type:

Optional[Preferences]

classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)¶

classmethod spawn_object(*args, **kwargs)¶