Controller

class negmas.negotiators.Controller(default_negotiator_type=None, default_negotiator_params=None, parent=None, auto_kill=True, **kwargs)[source]

Bases: negmas.types.rational.Rational

Controls the behavior of multiple negotiators in multiple negotiations.

The controller class MUST implement any methods of the negotiator class it is controlling with one added argument negotiator_id (str) which represents ID of the negotiator on which the method is being invoked (passed first).

Controllers for specific classes should inherit from this class and implement whatever methods they want to override on their ControlledNegotiator objects. For example, the SAO module defines SAOController that needs only to implement propose and respond .

Parameters

default_negotiator_type (Union[str, Type[ControlledNegotiator], None]) – The negotiator type to use for adding negotiator if no type is explicitly given.
default_negotiator_params (Optional[Dict[str, Any]]) – The parameters to use to construct the default negotiator type.
parent (Union[Controller, Agent, None]) – The parent which can be an Agent or another Controller
auto_kill (bool) – If True, negotiators will be killed once their negotiation finishes.
name – The controller name

Remarks:

Controllers should always call negotiator methods using the call method defined in this class. Direct calls may lead to infinite loops

Attributes Summary

`active_negotiators`	Returns the negotiators whose negotiations are running.
`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?
`id`	The unique ID of this entity
`name`	A convenient name of the entity (intended primarily for printing/logging/debugging).
`negotiators`	Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context.
`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`
`states`	Gets the current states of all negotiations as a mapping from negotiator ID to mechanism.
`type_name`	rtype `str`
`ufun`	Returns the preferences if it is a UtilityFunction else None
`uuid`	The unique ID of this entity

Methods Summary

`add_negotiator`(negotiator[, cntxt])	Adds a negotiator to the controller.
`after_join`(negotiator_id, nmi, state, *[, ...])	Called by children negotiators after joining a negotiation to inform the controller
`before_join`(negotiator_id, nmi, state, *[, ...])	Called by children negotiators to get permission to join negotiations
`call`(negotiator, method, args, *kwargs)	Calls the given method on the given negotiator safely without causing recursion.
`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.
`create_negotiator`([negotiator_type, name, cntxt])	Creates a negotiator passing it the context
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`join`(negotiator_id, nmi, state, *[, ...])	Called by the mechanism when the agent is about to enter a negotiation.
`kill_negotiator`(negotiator_id[, force])	Kills the negotiator sending it an `before_death` message.
`make_negotiator`([negotiator_type, name])	Creates a negotiator but does not add it to the controller.
`on_leave`(negotiator_id, state)	A call back called after leaving a negotiation.
`on_mechanism_error`(negotiator_id, state)	A call back called whenever an error happens in the mechanism.
`on_negotiation_end`(negotiator_id, state)	A call back called at each negotiation end
`on_negotiation_start`(negotiator_id, state)	A call back called at each negotiation start
`on_notification`(negotiator_id, notification, ...)
`on_preferences_changed`(changes)	Called to inform the entity that its ufun has changed.
`on_round_end`(negotiator_id, state)	A call back called at each negotiation round end
`on_round_start`(negotiator_id, state)	A call back called at each negotiation round start
`partner_agent_ids`(negotiator_id)	Finds the agent ID negotiating with one of our negotiators.
`partner_agent_names`(negotiator_id)	Finds the negotiator names negotiating with one of our negotiators.
`partner_negotiator_ids`(negotiator_id)	Finds the negotiator ID negotiating with one of our negotiators.
`partner_negotiator_names`(negotiator_id)	Finds the negotiator names negotiating with one of our negotiators.
`set_preferences`(value[, force])	Sets tha utility function/Preferences.
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)

Attributes Documentation

active_negotiators

Returns the negotiators whose negotiations are running.

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context

Return type: Dict[str, NegotiatorInfo]

crisp_ufun

Returns the preferences if it is a CrispUtilityFunction else None

Return type: UtilityFunction | None

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

id: The unique ID of this entity

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

negotiators

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context.

Return type: Dict[str, NegotiatorInfo]

preferences

The utility function attached to that object

Return type: Preferences | None

prob_ufun

Returns the preferences if it is a ProbUtilityFunction else None

Return type: ProbUtilityFunction | 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

Return type: Outcome | None

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

states

Gets the current states of all negotiations as a mapping from negotiator ID to mechanism.

Return type: Dict[str, MechanismState]

type_name

Return type: str

ufun

Returns the preferences if it is a UtilityFunction else None

Return type: BaseUtilityFunction | None

uuid: The unique ID of this entity

Methods Documentation

add_negotiator(negotiator, cntxt=None)[source]

Adds a negotiator to the controller.

Parameters

negotaitor – The negotaitor to add
name – negotiator name
cntxt (Optional[Any]) – The context to be associated with this negotiator.
**kwargs – any key-value pairs to be passed to the negotiator constructor

Return type

None

after_join(negotiator_id, nmi, state, *, preferences=None, role='negotiator')[source]

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

Parameters

negotiator_id (str) – The negotiator ID
nmi (AgentMechanismInterface) – The negotiation.
state (MechanismState) – The current state of the negotiation
preferences (UtilityFunction) – The ufun function to use before any discounting.
role (str) – role of the agent.

Return type

None

before_join(negotiator_id, nmi, state, *, preferences=None, role='negotiator')[source]

Called by children negotiators to get permission to join negotiations

Parameters

negotiator_id (str) – The negotiator ID
nmi (AgentMechanismInterface) – The negotiation.
state (MechanismState) – The current state of the negotiation
preferences (UtilityFunction) – The prefrences to use before any discounting.
role (str) – role of the agent.

Return type

bool

Returns

True if the negotiator is allowed to join the negotiation otherwise False

call(negotiator, method, *args, **kwargs)[source]

Calls the given method on the given negotiator safely without causing recursion. The controller MUST use this function to access any callable on the negotiator.

Parameters

negotiator (ControlledNegotiator) –
method (str) –
*args –
**kwargs –

Returns:

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.

create_negotiator(negotiator_type=None, name=None, cntxt=None, **kwargs)[source]

Creates a negotiator passing it the context

Parameters

negotiator_type (str | ControlledNegotiatorType | None) – Type of the negotiator to be created
name (str) – negotiator name
cntxt (Any) – The context to be associated with this negotiator.
**kwargs – any key-value pairs to be passed to the negotiator constructor

Return type

ControlledNegotiatorType

Returns

The negotiator to be controlled. None for failure

classmethod from_checkpoint(file_name, return_info=False)

Creates an object from a saved checkpoint

Parameters

file_name (Path | str) –
return_info – 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

join(negotiator_id, nmi, state, *, preferences=None, ufun=None, role='negotiator')[source]

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

Parameters

negotiator_id (str) – The negotiator ID
nmi (AgentMechanismInterface) – The negotiation.
state (MechanismState) – The current state of the negotiation
preferences (Preferences) – The preferences.
ufun (BaseUtilityFunction) – The ufun function to use before any discounting (overrides preferences)
role (str) – role of the agent.

Return type

bool

Returns

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

kill_negotiator(negotiator_id, force=False)[source]

Kills the negotiator sending it an before_death message.

Parameters

negotiator_id (str) – The ID of the negotiator to kill.
force (bool) – Whether to kill the negotiator in case it refused to die.

Remarks:

Killing a negotiator amounts to nothing more than removing it form the list of negotiators maintained by the controller.

Return type: None

make_negotiator(negotiator_type=None, name=None, **kwargs)[source]

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

Parameters

negotiator_type (str | ControlledNegotiatorType | None) – Type of the negotiator to be created. If None, A ControlledNegotiator negotiator will be controlled (which is fully controlled by the controller).
name (str) – negotiator name
**kwargs – any key-value pairs to be passed to the negotiator constructor

Return type

ControlledNegotiatorType

Returns

The negotiator to be controlled. None for failure

on_leave(negotiator_id, state)[source]

A call back called after leaving a negotiation.

Parameters

negotiator_id (str) – The negotiator ID
state (MechanismState) – MechanismState giving current state of the negotiation.

Return type

None

on_mechanism_error(negotiator_id, state)[source]

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

Parameters

negotiator_id (str) – The negotiator ID
state (MechanismState) – MechanismState giving current state of the negotiation.

Return type

None

on_negotiation_end(negotiator_id, state)[source]

A call back called at each negotiation end

Parameters

negotiator_id (str) – The negotiator ID
state (MechanismState) – MechanismState or one of its descendants giving the state at which the negotiation ended.

Return type

None

on_negotiation_start(negotiator_id, state)[source]

A call back called at each negotiation start

Parameters

negotiator_id (str) – The negotiator ID
state (MechanismState) – MechanismState giving current state of the negotiation.

Return type

None

on_notification(negotiator_id, notification, notifier)[source]

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

A call back called at each negotiation round end

Parameters

negotiator_id (str) – The negotiator ID
state (MechanismState) – MechanismState giving current state of the negotiation.

Return type

None

on_round_start(negotiator_id, state)[source]

A call back called at each negotiation round start

Parameters

negotiator_id (str) – The negotiator ID
state (MechanismState) – MechanismState giving current state of the negotiation.

Return type

None

partner_agent_ids(negotiator_id)[source]

Finds the agent ID negotiating with one of our negotiators.

Parameters: negotiator_id (str) – Our negotiator ID
Return type: Optional[List[str]]

partner_agent_names(negotiator_id)[source]

Finds the negotiator names negotiating with one of our negotiators.

Parameters: negotiator_id (str) – Our negotiator ID
Return type: Optional[List[str]]

partner_negotiator_ids(negotiator_id)[source]

Finds the negotiator ID negotiating with one of our negotiators.

Parameters: negotiator_id (str) – Our negotiator ID
Return type: Optional[List[str]]

partner_negotiator_names(negotiator_id)[source]

Finds the negotiator names negotiating with one of our negotiators.

Parameters: negotiator_id (str) – Our negotiator ID
Return type: Optional[List[str]]

set_preferences(value, force=False)

Sets tha utility function/Preferences.

Parameters

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

Return type

Preferences | None

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

classmethod spawn_object(*args, **kwargs)