SAOController

class negmas.sao.SAOController(default_negotiator_type=<class 'negmas.sao.negotiators.controlled.ControlledSAONegotiator'>, preferences=None, ufun=None, **kwargs)

Bases: Controller[SAONMI, SAOState, ControlledSAONegotiator]

A controller that can manage multiple negotiators taking full or partial control from them.

Parameters:

• default_negotiator_type – Default type to use when creating negotiators using this controller. The default type is ControlledSAONegotiator which passes full control to the controller.

• default_negotiator_params – Default paramters to pass to the default controller.

• auto_kill – Automatically kill the negotiator once its negotiation session is ended.

• name – Controller name

• preferences – The preferences of the controller.

• ufun – The ufun of the controller (overrides preferences).

Attributes Summary

active_negotiators	Returns the negotiators whose negotiations running or did not start yet.
crisp_ufun	Returns the preferences if it is a CrispUtilityFunction else None
default_negotiator_type
finished_negotiators	Returns the negotiators whose negotiations started and completed
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).
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
started_negotiators	Returns the negotiators whose negotiations started
states	Gets the current states of all negotiations as a mapping from negotiator ID to mechanism.
to_start_negotiators	Returns the negotiators whose negotiations did not start yet
type_name
ufun	Returns the preferences if it is a BaseUtilityFunction else None
unfinished_negotiators	Returns the negotiators whose negotiations started and did not complete yet
uuid	The unique ID of this entity

Methods Summary

add_negotiator(negotiator[, cntxt])	Adds a negotiator to the controller.
after_join(negotiator_id, *args[, ufun, ...])	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
is_clean()	Checks that the agent has no negotiators and that all its intermediate data-structures are reset
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)
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.
propose(negotiator_id, state[, dest])
reset()	Resets the controller and kills any negotiators it may have
respond(negotiator_id, state[, source])
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

active_negotiators

Returns the negotiators whose negotiations running or did not start yet.

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

crisp_ufun

Returns the preferences if it is a CrispUtilityFunction else None

default_negotiator_type

finished_negotiators

Returns the negotiators whose negotiations started and completed

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

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

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.

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

started_negotiators

Returns the negotiators whose negotiations started

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

states

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

to_start_negotiators

Returns the negotiators whose negotiations did not start yet

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

type_name

ufun

Returns the preferences if it is a BaseUtilityFunction else None

unfinished_negotiators

Returns the negotiators whose negotiations started and did not complete yet

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

uuid

The unique ID of this entity

Methods Documentation

add_negotiator(negotiator: Negotiator, cntxt: Any = None) → None

Adds a negotiator to the controller.

Parameters:

• negotaitor – The negotaitor to add

• name – negotiator name

• cntxt – The context to be associated with this negotiator.

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

after_join(negotiator_id, *args, ufun=None, preferences=None, **kwargs) → None

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

Parameters:

• negotiator_id – The negotiator ID

• nmi (SAONMI) – The negotiation.

• state (SAOState) – The current state of the negotiation

• ufun (UtilityFunction) – The ufun function to use before any discounting.

• role (str) – role of the agent.

before_join(negotiator_id: str, nmi: SAONMI, state: SAOState, *, preferences: Preferences | None = None, role: str = 'negotiator') → bool

Called by children negotiators to get permission to join negotiations

Parameters:

• negotiator_id – The negotiator ID

• nmi (SAONMI) – The negotiation.

• state (SAOState) – The current state of the negotiation

• ufun (UtilityFunction) – The ufun function to use before any discounting.

• role (str) – role of the agent.

Returns:

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

call(negotiator: ControlledNegotiator, method: str, *args, **kwargs)

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

• method

• *args

• **kwargs

Returns:

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.

create_negotiator(negotiator_type=None, name: str | None = None, cntxt: Any = None, **kwargs)

Creates a negotiator passing it the context

Parameters:

• negotiator_type – Type of the negotiator to be created

• name – negotiator name

• cntxt – The context to be associated with this negotiator.

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

Returns:

The negotiator to be controlled. None for failure

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

is_clean() → bool

Checks that the agent has no negotiators and that all its intermediate data-structures are reset

join(negotiator_id: str, 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:

• negotiator_id – The negotiator ID

• nmi (AgentMechanismInterface) – The negotiation.

• state (TState) – 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.

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: str, force: bool = False) → None

Kills the negotiator sending it an before_death message.

Parameters:

• negotiator_id – The ID of the negotiator to kill.

• force – 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.

make_negotiator(negotiator_type: str | TControlledNegotiator | None = None, name: str | None = None, **kwargs) → TControlledNegotiator

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. If None, A ControlledNegotiator negotiator will be controlled (which is fully controlled by the controller).

• name – negotiator name

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

Returns:

The negotiator to be controlled. None for failure

on_leave(negotiator_id: str, state: TState) → None

A call back called after leaving a negotiation.

Parameters:

• negotiator_id – The negotiator ID

• state – TState giving current state of the negotiation.

on_mechanism_error(negotiator_id: str, state: TState) → None

on_negotiation_end(negotiator_id: str, state: TState) → None

A call back called at each negotiation end

Parameters:

• negotiator_id – The negotiator ID

• state – TState or one of its descendants giving the state at which the negotiation ended.

on_negotiation_start(negotiator_id: str, state: TState) → None

A call back called at each negotiation start

Parameters:

• negotiator_id – The negotiator ID

• state – TState giving current state of the negotiation.

on_notification(negotiator_id: str, notification: Notification, notifier: str)

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(negotiator_id: str, state: TState) → None

A call back called at each negotiation round end

Parameters:

• negotiator_id – The negotiator ID

• state – TState giving current state of the negotiation.

on_round_start(negotiator_id: str, state: TState) → None

A call back called at each negotiation round start

Parameters:

• negotiator_id – The negotiator ID

• state – TState giving current state of the negotiation.

partner_agent_ids(negotiator_id: str) → list[str] | None

Finds the agent ID negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

partner_agent_names(negotiator_id: str) → list[str] | None

Finds the negotiator names negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

partner_negotiator_ids(negotiator_id: str) → list[str] | None

Finds the negotiator ID negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

partner_negotiator_names(negotiator_id: str) → list[str] | None

Finds the negotiator names negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

propose(negotiator_id: str, state: SAOState, dest: str | None = None) → tuple | ExtendedOutcome | None

reset()

Resets the controller and kills any negotiators it may have

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

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)