SingleAgreementAspirationAgent

class scml.oneshot.SingleAgreementAspirationAgent(*args, **kwargs)[source]

Bases: scml.oneshot.agent.OneShotSyncAgent

Uses a time-based strategy to accept a single agreement from the set it is considering.

Attributes Summary

active_negotiators

Returns the negotiators whose negotiations are running.

awi

Returns a OneShotAWI object for accessing the simulation.

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

internal_state

Returns the internal state of the agent for debugging purposes.

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.

running_negotiations

The negotiations currently requested by the agent.

short_type_name

Returns a short name of the type of this entity

states

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

type_name

Returns the name of the type of this entity

type_postfix

ufun

Returns the preferences if it is a UtilityFunction else None

unsigned_contracts

All contracts that are not yet signed.

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

before_step()

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

choose_agents(offers, outcome)

Selects an appropriate way to distribute this outcome to agents with given IDs.

connect_to_2021_adapter(owner)

Connects the agent to its adapter (used internally)

connect_to_oneshot_adapter(owner)

Connects the agent to its adapter (used internally)

counter_all(offers, states)

Calculate a response to all offers from all negotiators (negotiator ID is the key).

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

first_offer(negotiator_id)

Finds the first offer for this given negotiator.

first_proposals()

Gets a set of proposals to use for initializing the negotiation.

from_checkpoint(file_name[, return_info])

Creates an object from a saved checkpoint

get_ami(partner_id)

Returns the SAONMI (Agent Mechanism Interface) connecting the agent to the negotiation mechanism for the given partner.

get_negotiator(partner_id)

Returns the negotiator corresponding to the given partner ID.

get_nmi(partner_id)

Returns the SAONMI (Agent Mechanism Interface) connecting the agent to the negotiation mechanism for the given partner.

init()

Called once after the AWI is set.

init_()

Called to initialize the agent after the world is initialized.

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.

make_ufun([add_exogenous])

Creates a utility function for the agent.

on_contract_breached(contract, breaches, ...)

rtype

None

on_contract_executed(contract)

rtype

None

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_failure(partners, annotation, ...)

Called whenever a negotiation ends without agreement.

on_negotiation_start(negotiator_id, state)

A call back called at each negotiation start

on_negotiation_success(contract, mechanism)

Called whenever a negotiation ends with agreement.

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)

Proposes an offer to one of the partners.

reset()

Resets the controller and kills any negotiators it may have

respond(negotiator_id, state, offer)

Responds to an offer from one of the partners.

set_preferences(value[, force])

Sets tha utility function/Preferences.

sign_all_contracts(contracts)

Signs all contracts (used internally)

spawn([spawn_as, spawn_params])

spawn_object(*args, **kwargs)

step()

Called every step.

step_()

Called at every time-step.

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]

awi

Returns a OneShotAWI object for accessing the simulation.

Return type

OneShotAWI

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

internal_state

Returns the internal state of the agent for debugging purposes.

Remarks:
  • In your agent, you can add any key-value pair to this dict and then use agent_log_* methods to log this information at any point.

Return type

dict[str, Any]

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

tuple | 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

running_negotiations

The negotiations currently requested by the agent.

Return type

list[RunningNegotiationInfo]

Returns

A list of negotiation information objects (RunningNegotiationInfo)

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

type_postfix
ufun

Returns the preferences if it is a UtilityFunction else None

Return type

BaseUtilityFunction | None

unsigned_contracts

All contracts that are not yet signed.

Return type

list[Contract]

uuid

The unique ID of this entity

Methods Documentation

add_negotiator(negotiator, cntxt=None)

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, *args, ufun=None, preferences=None, **kwargs)

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

Parameters
  • negotiator_id – The negotiator ID

  • nmi (NegotiatorMechanismInterface) – The negotiation.

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

  • ufun (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')

Called by children negotiators to get permission to join negotiations

Parameters
  • negotiator_id (str) – The negotiator ID

  • nmi (NegotiatorMechanismInterface) – The negotiation.

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

  • ufun (UtilityFunction) – The ufun function 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

before_step()[source]
call(negotiator, method, *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 (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]

choose_agents(offers, outcome)[source]

Selects an appropriate way to distribute this outcome to agents with given IDs.

connect_to_2021_adapter(owner)

Connects the agent to its adapter (used internally)

connect_to_oneshot_adapter(owner)

Connects the agent to its adapter (used internally)

counter_all(offers, states)[source]

Calculate a response to all offers from all negotiators (negotiator ID is the key).

Parameters
  • offers – Maps negotiator IDs to offers

  • states – Maps negotiator IDs to offers AT the time the offers were made.

Returns

A dictionary mapping negotiator ID to an SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.

Remarks:
  • The response type CANNOT be WAIT.

  • If the system determines that a loop is formed, the agent may

receive this call for a subset of negotiations not all of them.

classmethod create(*args, **kwargs)

Creates an object and returns a proxy to it.

create_negotiator(negotiator_type=None, name=None, cntxt=None, **kwargs)

Creates a negotiator passing it the context

Parameters
  • negotiator_type (Union[str, TypeVar(ControlledNegotiatorType, bound= SAONegotiator), None]) – Type of the negotiator to be created

  • name (Optional[str]) – 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

TypeVar(ControlledNegotiatorType, bound= SAONegotiator)

Returns

The negotiator to be controlled. None for failure

first_offer(negotiator_id)

Finds the first offer for this given negotiator. By default it will be the best offer

Parameters

negotiator_id (str) – The ID of the negotiator

Return type

tuple | None

Returns

The first offer to use.

Remarks:

Default behavior is to use the ufun defined for the controller if any then try the ufun defined for the negotiator. If neither exists, the first offer will be None.

first_proposals()[source]

Gets a set of proposals to use for initializing the negotiation.

Return type

Dict[str, tuple]

Returns

A dictionary mapping each negotiator (in self.negotiators dict) to an outcome to be used as the first proposal if the agent is to start a negotiation.

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

get_ami(partner_id)

Returns the SAONMI (Agent Mechanism Interface) connecting the agent to the negotiation mechanism for the given partner.

Return type

SAONMI

get_negotiator(partner_id)

Returns the negotiator corresponding to the given partner ID.

Remarks:
  • Note that the negotiator ID and the partner ID are always the same.

Return type

SAONegotiator

get_nmi(partner_id)

Returns the SAONMI (Agent Mechanism Interface) connecting the agent to the negotiation mechanism for the given partner.

Return type

SAONMI

init()

Called once after the AWI is set.

Remarks:
  • Use this for any proactive initialization code.

init_()

Called to initialize the agent after the world is initialized. the AWI is accessible at this point.

join(negotiator_id, 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
  • 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)

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)

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

Parameters
  • negotiator_type (Union[str, TypeVar(ControlledNegotiatorType, bound= Negotiator), None]) – Type of the negotiator to be created. If None, A ControlledNegotiator negotiator will be controlled (which is fully controlled by the controller).

  • name (Optional[str]) – negotiator name

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

Return type

TypeVar(ControlledNegotiatorType, bound= Negotiator)

Returns

The negotiator to be controlled. None for failure

make_ufun(add_exogenous=False)

Creates a utility function for the agent.

Parameters

add_exogenous – If True then the exogenous contracts of the agent will be automatically added whenever the ufun is evaluated for any set of contracts, offers or otherwise.

Remarks:
  • You can always as assume that self.ufun returns the ufun for your. You will not need to directly use this method in most cases.

on_contract_breached(contract, breaches, resolution)
Return type

None

on_contract_executed(contract)
Return type

None

on_leave(negotiator_id, state)

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)

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)

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_failure(partners, annotation, mechanism, state)

Called whenever a negotiation ends without agreement.

Parameters
  • partners (list[str]) – List of the partner IDs consisting from self and the opponent.

  • annotation (dict[str, Any]) – The annotation of the negotiation including the seller ID, buyer ID, and the product.

  • mechanism (NegotiatorMechanismInterface) – The NegotiatorMechanismInterface instance containing all information about the negotiation.

  • state (MechanismState) – The final state of the negotiation of the type SAOState including the agreement if any.

Return type

None

on_negotiation_start(negotiator_id, state)

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_negotiation_success(contract, mechanism)

Called whenever a negotiation ends with agreement.

Parameters
  • contract (Contract) – The Contract agreed upon.

  • mechanism (NegotiatorMechanismInterface) – The NegotiatorMechanismInterface instance containing all information about the negotiation that led to the Contract if any.

Return type

None

on_notification(negotiator_id, notification, notifier)
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)

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)

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)

Finds the agent ID negotiating with one of our negotiators.

Parameters

negotiator_id (str) – Our negotiator ID

Return type

list[str] | None

partner_agent_names(negotiator_id)

Finds the negotiator names negotiating with one of our negotiators.

Parameters

negotiator_id (str) – Our negotiator ID

Return type

list[str] | None

partner_negotiator_ids(negotiator_id)

Finds the negotiator ID negotiating with one of our negotiators.

Parameters

negotiator_id (str) – Our negotiator ID

Return type

list[str] | None

partner_negotiator_names(negotiator_id)

Finds the negotiator names negotiating with one of our negotiators.

Parameters

negotiator_id (str) – Our negotiator ID

Return type

list[str] | None

propose(negotiator_id, state)

Proposes an offer to one of the partners.

Parameters
  • negotiator_id (str) – ID of the negotiator (and partner)

  • state (MechanismState) – Mechanism state including current step

Return type

tuple | None

Returns

an outcome to offer.

reset()

Resets the controller and kills any negotiators it may have

respond(negotiator_id, state, offer)

Responds to an offer from one of the partners.

Parameters
  • negotiator_id (str) – ID of the negotiator (and partner)

  • state (SAOState) – Mechanism state including current step

  • offer (tuple) – The offer received.

Return type

ResponseType

Returns

A response type which can either be reject, accept, or end negotiation.

Remarks:

default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise

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

sign_all_contracts(contracts)

Signs all contracts (used internally)

Return type

list[str | None]

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

Called every step.

Remarks:
  • Use this for any proactive code that needs to be done every simulation step.

step_()

Called at every time-step. This function is called directly by the world.