Controller

class negmas.negotiators.Controller(default_negotiator_type: Union[str, Type[negmas.negotiators.PassThroughNegotiator]] = None, default_negotiator_params: Dict[str, Any] = None, parent: Union[Controller, Agent] = None, auto_kill: bool = True, **kwargs)[source]

Bases: negmas.common.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 PassThroughNegotiator objects. For example, the SAO module defines SAOController that needs only to implement propose and respond .

Parameters
  • default_negotiator_type – The negotiator type to use for adding negotiator if no type is explicitly given.

  • default_negotiator_params – The parameters to use to construct the default negotiator type.

  • parent – The parent which can be an Agent or another Controller

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

negotiators

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

Methods Summary

add_negotiator(negotiator[, cntxt])

Adds a negotiator to the controller

after_join(negotiator_id, ami, state, *[, …])

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

before_join(negotiator_id, ami, 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.

create_negotiator([negotiator_type, name, cntxt])

Creates a negotiator passing it the context

join(negotiator_id, ami, state, *[, ufun, role])

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

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

negotiators

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

Methods Documentation

add_negotiator(negotiator: negmas.negotiators.Negotiator, cntxt: Optional[Any] = None)None[source]

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: str, ami: negmas.common.AgentMechanismInterface, state: negmas.common.MechanismState, *, ufun: Optional[UtilityFunction] = None, role: str = 'agent')None[source]

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

Parameters
before_join(negotiator_id: str, ami: negmas.common.AgentMechanismInterface, state: negmas.common.MechanismState, *, ufun: Optional[UtilityFunction] = None, role: str = 'agent')bool[source]

Called by children negotiators to get permission to join negotiations

Parameters
Returns

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

call(negotiator: negmas.negotiators.PassThroughNegotiator, method: str, *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

  • method

  • *args

  • **kwargs

Returns:

create_negotiator(negotiator_type: Optional[Union[str, Type[negmas.negotiators.PassThroughNegotiator]]] = None, name: Optional[str] = None, cntxt: Optional[Any] = None, **kwargs)negmas.negotiators.PassThroughNegotiator[source]

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

join(negotiator_id: str, ami: negmas.common.AgentMechanismInterface, state: negmas.common.MechanismState, *, ufun: Optional[UtilityFunction] = None, role: str = 'agent')bool[source]

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

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

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: Optional[Union[str, Type[negmas.negotiators.PassThroughNegotiator]]] = None, name: Optional[str] = None, **kwargs)negmas.negotiators.PassThroughNegotiator[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

on_leave(negotiator_id: str, state: negmas.common.MechanismState)None[source]

A call back called after leaving a negotiation.

Parameters
  • negotiator_id – The negotiator ID

  • stateMechanismState giving current state of the negotiation.

on_mechanism_error(negotiator_id: str, state: negmas.common.MechanismState)None[source]

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

Parameters
  • negotiator_id – The negotiator ID

  • stateMechanismState giving current state of the negotiation.

on_negotiation_end(negotiator_id: str, state: negmas.common.MechanismState)None[source]

A call back called at each negotiation end

Parameters
  • negotiator_id – The negotiator ID

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

on_negotiation_start(negotiator_id: str, state: negmas.common.MechanismState)None[source]

A call back called at each negotiation start

Parameters
  • negotiator_id – The negotiator ID

  • stateMechanismState giving current state of the negotiation.

on_notification(negotiator_id: str, notification: negmas.events.Notification, notifier: str)[source]
on_round_end(negotiator_id: str, state: negmas.common.MechanismState)None[source]

A call back called at each negotiation round end

Parameters
  • negotiator_id – The negotiator ID

  • stateMechanismState giving current state of the negotiation.

on_round_start(negotiator_id: str, state: negmas.common.MechanismState)None[source]

A call back called at each negotiation round start

Parameters
  • negotiator_id – The negotiator ID

  • stateMechanismState giving current state of the negotiation.

partner_agent_ids(negotiator_id: str)Optional[List[str]][source]

Finds the agent ID negotiating with one of our negotiators.

Parameters

negotiator_id – Our negotiator ID

partner_agent_names(negotiator_id: str)Optional[List[str]][source]

Finds the negotiator names negotiating with one of our negotiators.

Parameters

negotiator_id – Our negotiator ID

partner_negotiator_ids(negotiator_id: str)Optional[List[str]][source]

Finds the negotiator ID negotiating with one of our negotiators.

Parameters

negotiator_id – Our negotiator ID

partner_negotiator_names(negotiator_id: str)Optional[List[str]][source]

Finds the negotiator names negotiating with one of our negotiators.

Parameters

negotiator_id – Our negotiator ID