RealComparatorNegotiator

class negmas.negotiators.RealComparatorNegotiator(*args, **kwargs)

Bases: Negotiator

A negotiator that can be asked to evaluate outcomes using its internal ufun.

Th change the way it evaluates outcomes, override compare_real

It has the compare-real capability

Attributes Summary

ami
annotation	Returns the private information (annotation) not shared with other negotiators
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
opponent_ufun
owner	Returns the owner agent of the negotiator
parent	Returns the parent controller
preferences	The utility function attached to that object
private_info	Returns the private information (annotation) not shared with other negotiators
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
type_name
ufun	Returns the preferences if it is a BaseUtilityFunction else None
uuid	The unique ID of this entity

Methods Summary

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.
difference(first, second)	Compares two offers using the ufun returning the difference in their utility
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.
is_better(first, second)	Compares two offers using the ufun returning whether the first is better than the second
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 the agent receives a notification
on_notification_(notification, notifier)	Called when a notification is received.
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
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.
set_id(id)	Sets the unique ID of this entity
set_preferences(value[, force, ...])	Sets the utility function/Preferences.
spawn([spawn_as, spawn_params])
spawn_object(*args, **kwargs)

Attributes Documentation

ami

annotation

Returns the private information (annotation) not shared with other negotiators

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

opponent_ufun

owner

Returns the owner agent of the negotiator

parent

Returns the parent controller

preferences

The utility function attached to that object

private_info

Returns the private information (annotation) not shared with other negotiators

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.

Remarks:

• Reserved outcomes are defined for OrdinalPreferences.

See also

reserved_value

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.

short_type_name

type_name

ufun

Returns the preferences if it is a BaseUtilityFunction else None

uuid

The unique ID of this entity

Methods Documentation

add_capabilities(capabilities: dict) → None

Adds named capabilities to the negotiator.

Parameters:

capabilities – The capabilities to be added as a dict

Returns:

None

Remarks:

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

add_handler(notification_type: str, callback: Callable[[Notification, str], bool])

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 – Notification type as specificed in the type member of the Notification class

• callback – 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: dict[str, Any]) → bool

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

cancel(reason=None) → 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.

checkpoint(path: PathLike, file_name: str | None = None, info: dict[str, Any] | None = None, exist_ok: bool = False, single_checkpoint: bool = True, step_attribs: tuple[str, ...] = ('current_step', '_current_step', '_Entity__current_step', '_step')) → Path

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

Parameters:

• path – Full path to a directory to store the checkpoint

• file_name – Name of the file to dump into. If not given, a unique name is created

• info – Information to save with the checkpoint (must be json serializable)

• exist_ok – If true, override existing dump

• single_checkpoint – If true, keep a single checkpoint for the last step

• step_attribs – 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

Returns:

full path to the file used to save the checkpoint

classmethod checkpoint_info(file_name: Path | str) → dict[str, Any]

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

Parameters:

file_name – Name of the object

Returns:

classmethod create(*args, **kwargs)

Creates an object and returns a proxy to it.

difference(first: Outcome, second: Outcome) → float

Compares two offers using the ufun returning the difference in their utility

Parameters:

• first – First outcome to be compared

• second – Second outcome to be compared

Returns:

An estimate of the differences between the two outcomes. It can be a real number between -1, 1 or a probability distribution over the same range.

Return type:

“Value”

classmethod from_checkpoint(file_name: Path | str, return_info: bool = False) → NamedObject | tuple[NamedObject, dict[str, Any]]

Creates an object from a saved checkpoint

Parameters:

• file_name

• return_info – If True, tbe information saved when the file was dumped are returned

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: str) → list[Callable[[Notification, str], bool]]

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.

is_acceptable_as_agreement(outcome: Outcome) → bool

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.

is_better(first: Outcome | None, second: Outcome | None) → bool | None

Compares two offers using the ufun returning whether the first is better than the second

Parameters:

• first – First outcome to be compared

• second – Second outcome to be compared

Returns:

True if utility(first) > utility(second) + epsilon None if |utility(first) - utility(second)| <= epsilon or the utun is not defined False if utility(first) < utility(second) - epsilon

isin(negotiation_id: str | None) → bool

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: TNMI, state: TState, *, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, role: str = 'negotiator') → bool

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

Parameters:

• nmi – The negotiation.

• state – The current state of the negotiation

• preferences – The preferences used by the negotiator (see ufun )

• ufun – The ufun function to use (overrides preferences )

• role – role of the negotiator.

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:

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

  2. The negotiator is already in a negotiation

on_leave(state: TState) → None

A call back called after leaving a negotiation.

Parameters:

state – 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

on_mechanism_error(state: TState) → None

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

Parameters:

state – MechanismState giving current state of the negotiation.

Remarks:

• The default behavior is to do nothing.

• Override this to hook some action

on_negotiation_end(state: TState) → None

A call back called at each negotiation end

Parameters:

state – 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.

on_negotiation_start(state: TState) → None

A call back called at each negotiation start

Parameters:

state – 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.

on_notification(notification: Notification, notifier: str)

Called whenever the agent receives a notification

Parameters:

• notification – The notification!!

• notifier – The notifier!!

Returns:

None

Remarks:

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

on_notification_(notification: Notification, notifier: str) → bool

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

Parameters:

• notification

• notifier

Returns:

on_preferences_changed(changes: list[PreferencesChange])

Called to inform the entity that its ufun has changed.

Parameters:

changes – 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: TState) → None

A call back called at each negotiation round end

Parameters:

state – MechanismState giving current state of the negotiation.

Remarks:

• The default behavior is to do nothing.

• Override this to hook some action

on_round_start(state: TState) → None

A call back called at each negotiation round start

Parameters:

state – MechanismState giving current state of the negotiation.

Remarks:

• The default behavior is to do nothing.

• Override this to hook some action.

remove_capability(name: str) → None

Removes named capability from the negotiator

Parameters:

capabilities – The capabilities to be added as a dict

Returns:

None

Remarks:

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

remove_handler(notification_type: str, callback: Callable[[Notification, str], bool]) → bool

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

Parameters:

• notification_type – Notification type as specificed in the type member of the Notification class

• callback – 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:

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).

set_id(id: str)

Sets the unique ID of this entity

set_preferences(value: Preferences | None, force=False, ignore_exceptions: bool = False) → Preferences | None

Sets the utility function/Preferences.

Parameters:

• value – The value to set to

• force – If true, on_preferecnes_changed() will always be called even if value == self.preferences

classmethod spawn(spawn_as='object', spawn_params: dict[str, Any] | None = None, *args, **kwargs)

classmethod spawn_object(*args, **kwargs)