Adapter

class negmas.situated.Adapter(obj, include_adapter_type_name=None, include_obj_type_name=True, **kwargs)[source]

Bases: Agent

Represents an adapter agent that makes some included object act as an agent in some world.

Parameters:

obj – The object to be adapted.
include_adapter_type_name (bool | None) – Whether to include the adapter type name. If None, then it will be included if it does not start with and underscore.
include_obj_type_name – Whether to include object type name in this adapter’s type name
type_postfix – A string to add to the end of the type name

Remarks:

Other than keeping an internal copy of the adapted object under obj, this class is used primarily to provide a way to give good type_name and short_type_name properties that combine the name of the adapter and the name of the enclosed object nicely.

The adapted object must be an Entity.

The World class uses the type names from this adapter whenever it needs to get a type-name (either type_name or short_type_name)

Attributes Summary

`accepted_negotiation_requests`	A list of negotiation requests sent to this agent that are already accepted by it.
`adapted_object`
`awi`	Gets the Agent-world interface.
`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
`initialized`	Was the agent initialized (i.e. was init_() called).
`name`	A convenient name of the entity (intended primarily for printing/logging/debugging).
`negotiation_requests`	A list of the negotiation requests sent by this agent that are not yet accepted or rejected.
`preferences`	The utility function attached to that object
`prob_ufun`	Returns the preferences if it is a ProbUtilityFunction else None
`requested_negotiations`	The negotiations currently requested by the agent.
`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
`type_name`	Returns a short name of the type of this entity
`type_postfix`
`ufun`	Returns the preferences if it is a `BaseUtilityFunction` else None
`unsigned_contracts`	All contracts that are not yet signed.
`uuid`	The unique ID of this entity

Methods Summary

`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_negotiation_request`(issues, partners, ...)	Creates a new `NegotiationRequestInfo` record and returns itS ID
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`from_config`(config[, section, ...])	Creates an object of this class given the configuration info.
`init`()	Override this method to modify initialization logic
`init_`()	Called to initialize the agent after the world is initialized.
`notify`(notifiable, notification)
`on_contract_breached`(contract, breaches, ...)	Called after complete processing of a contract that involved a breach.
`on_contract_cancelled`(contract, rejectors)	Called whenever at least a partner did not sign the contract
`on_contract_cancelled_`(contract, rejectors)	Called whenever at least a partner did not sign the contract
`on_contract_executed`(contract)	Called after successful contract execution for which the agent is one of the partners.
`on_contract_signed`(contract)	Called whenever a contract is signed by all partners
`on_contract_signed_`(contract)	Called whenever a contract is signed by all partners
`on_contracts_finalized`(signed, cancelled, ...)	Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)
`on_event`(event, sender)
`on_neg_request_accepted`(req_id, mechanism)	Called when a requested negotiation is accepted
`on_neg_request_accepted_`(req_id, mechanism)	Called when a requested negotiation is accepted
`on_neg_request_rejected`(req_id, by)	Called when a requested negotiation is rejected
`on_neg_request_rejected_`(req_id, by)	Called when a requested negotiation is rejected
`on_negotiation_failure`(partners, annotation, ...)	Called whenever a negotiation ends without agreement
`on_negotiation_failure_`(partners, ...)	Called whenever a negotiation ends without agreement
`on_negotiation_success`(contract, mechanism)	Called whenever a negotiation ends with agreement
`on_negotiation_success_`(contract, mechanism)	Called whenever a negotiation ends with agreement
`on_preferences_changed`(changes)	Called to inform the entity that its ufun has changed.
`on_simulation_step_ended`()	Will be called at the end of the simulation step after everything else
`on_simulation_step_started`()	Will be called at the beginning of the simulation step before everything else (except init)
`read_config`(config[, section])	Reads the configuration from a file or a dict and prepares it for parsing.
`respond_to_negotiation_request_`(initiator, ...)	Called when a negotiation request is received
`respond_to_renegotiation_request`(contract, ...)	Called to respond to a renegotiation request
`set_id`(id)	Sets the unique ID of this entity
`set_preferences`(value[, force, ...])	Sets the utility function/Preferences.
`set_renegotiation_agenda`(contract, breaches)	Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails
`sign_all_contracts`(contracts)	Called to sign all contracts concluded in a single step by this agent
`sign_contract`(contract)	Called after the signing delay from contract conclusion to sign the contract.
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)
`step`()	Override this method to modify stepping logic
`step_`()	Called at every time-step.

Attributes Documentation

accepted_negotiation_requests

A list of negotiation requests sent to this agent that are already accepted by it.

Remarks:

These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to running_negotiations

adapted_object

awi: Gets the Agent-world interface.

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

initialized: Was the agent initialized (i.e. was init_() called)

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

negotiation_requests

A list of the negotiation requests sent by this agent that are not yet accepted or rejected.

Remarks:

These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to running_negotiations

preferences: The utility function attached to that object

prob_ufun: Returns the preferences if it is a ProbUtilityFunction else None

requested_negotiations

The negotiations currently requested by the agent.

Returns:: A list of negotiation request information objects (NegotiationRequestInfo)

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.

running_negotiations

The negotiations currently requested by the agent.

Returns:: A list of negotiation information objects (RunningNegotiationInfo)

short_type_name: Returns a short name of the type of this entity

type_name: Returns a short name of the type of this entity

type_postfix

ufun: Returns the preferences if it is a BaseUtilityFunction else None

unsigned_contracts: All contracts that are not yet signed.

uuid: The unique ID of this entity

Methods Documentation

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 (str | None) – Name of the file to dump into. If not given, a unique name is created
info (dict[str, Any] | None) – 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
Return type:: dict[str, Any]

Returns:

classmethod create(*args, **kwargs): Creates an object and returns a proxy to it.

create_negotiation_request(issues, partners, annotation, negotiator, extra)

Creates a new NegotiationRequestInfo record and returns itS ID

Parameters:

issues (list[Issue] | tuple[Issue, ...]) – negotiation issues
partners (list[str]) – partners
annotation (dict[str, Any] | None) – annotation
negotiator (Negotiator | None) – the negotiator to use
extra (dict[str, Any] | None) – any extra information

Return type:

str

Returns:

A unique identifier for this negotiation info structure

classmethod from_checkpoint(file_name, return_info=False)

Creates an object from a saved checkpoint

Parameters:

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

classmethod from_config(config, section=None, ignore_children=True, try_parsing_children=True, scope=None)

Creates an object of this class given the configuration info.

Parameters:

config (str | dict) – Either a file name or a dictionary
section (str | None) – A section in the file or a key in the dictionary to use for loading params
ignore_children (bool) – If true then children will be ignored and there will be a single return
try_parsing_children (bool) – If true the children will first be parsed as ConfigReader classes if they are not
int (simple types (e.g.)
str
float
Iterable[int|str|float]
scope – The scope at which to evaluate any child classes. This MUST be passed as scope=globals() if you are
parsed. (having any children that are to be)

Returns:

An object of cls if ignore_children is True or a tuple with an object of cls and a dictionary with children that were not parsed.

Remarks:

This function will return an object of its class after passing the key-value pairs found in the config to the init function.

Requiring passing scope=globals() to this function is to get around the fact that in python eval() will be called with a globals dictionary based on the module in which the function is defined not called. This means that in general when eval() is called to create the children, it will not have access to the class definitions of these children (except if they happen to be imported in this file). To avoid this problem causing an undefined_name exception, the caller must pass her globals() as the scope.

init()[source]: Override this method to modify initialization logic

init_(): Called to initialize the agent after the world is initialized. the AWI is accessible at this point.

notify(notifiable, notification)

abstract on_contract_breached(contract, breaches, resolution)

Called after complete processing of a contract that involved a breach.

Parameters:

contract (Contract) – The contract
breaches (list[Breach]) – All breaches committed (even if they were resolved)
resolution (Contract | None) – The resolution contract if re-negotiation was successful. None if not.

Return type:

None

on_contract_cancelled(contract, rejectors)

Called whenever at least a partner did not sign the contract

Return type:: None

on_contract_cancelled_(contract, rejectors)

Called whenever at least a partner did not sign the contract

Return type:: None

abstract on_contract_executed(contract)

Called after successful contract execution for which the agent is one of the partners.

Return type:: None

on_contract_signed(contract)

Called whenever a contract is signed by all partners

Return type:: None

on_contract_signed_(contract)

Called whenever a contract is signed by all partners

Return type:: None

on_contracts_finalized(signed, cancelled, rejectors)

Called for all contracts in a single step to inform the agent about which were finally signed and which were rejected by any agents (including itself)

Parameters:

signed (list[Contract]) – A list of signed contracts. These are binding
cancelled (list[Contract]) – A list of cancelled contracts. These are not binding
rejectors (list[list[str]]) – A list of lists where each of the internal lists gives the rejectors of one of the cancelled contracts. Notice that it is possible that this list is empty which means that the contract other than being rejected by any agents (if that was possible in the specific world).

Return type:

None

Remarks:

The default implementation is to call on_contract_signed for singed contracts and on_contract_cancelled for cancelled contracts

on_event(event, sender)

abstract on_neg_request_accepted(req_id, mechanism): Called when a requested negotiation is accepted

on_neg_request_accepted_(req_id, mechanism): Called when a requested negotiation is accepted

abstract on_neg_request_rejected(req_id, by)

Called when a requested negotiation is rejected

Parameters:

req_id (str) – The request ID passed to _request_negotiation
by (list[str] | None) – A list of agents that refused to participate or None if the failure was for another reason

on_neg_request_rejected_(req_id, by)

Called when a requested negotiation is rejected

Parameters:

req_id (str) – The request ID passed to _request_negotiation
by (list[str] | None) – A list of agents that refused to participate or None if the failure was for another reason

abstract on_negotiation_failure(partners, annotation, mechanism, state)

Called whenever a negotiation ends without agreement

Return type:: None

on_negotiation_failure_(partners, annotation, mechanism, state)

Called whenever a negotiation ends without agreement

Return type:: None

abstract on_negotiation_success(contract, mechanism)

Called whenever a negotiation ends with agreement

Return type:: None

on_negotiation_success_(contract, mechanism)

Called whenever a negotiation ends with agreement

Return type:: None

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_simulation_step_ended(): Will be called at the end of the simulation step after everything else

on_simulation_step_started(): Will be called at the beginning of the simulation step before everything else (except init)

classmethod read_config(config, section=None)

Reads the configuration from a file or a dict and prepares it for parsing.

Parameters:

config (str | dict) – Either a file name or a dictionary
section (str | None) – A section in the file or a key in the dictionary to use for loading params

Return type:

dict[str, Any]

Returns:

A dict ready to be parsed by from_config

Remarks:

respond_to_negotiation_request_(initiator, partners, issues, annotation, mechanism, role, req_id)

Called when a negotiation request is received

Return type:: Negotiator | None

abstract respond_to_renegotiation_request(contract, breaches, agenda)

Called to respond to a renegotiation request

Parameters:

agenda (RenegotiationRequest)
contract (Contract)
breaches (list[Breach])

Return type:

Negotiator | None

Returns:

set_id(id): Sets the unique ID of this entity

set_preferences(value, force=False, ignore_exceptions=False)

Sets the 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

abstract set_renegotiation_agenda(contract, breaches)

Received by partners in ascending order of their total breach levels in order to set the renegotiation agenda when contract execution fails

Parameters:

contract (Contract) – The contract being breached
breaches (list[Breach]) – All breaches on contract

Return type:

RenegotiationRequest | None

Returns:

Renegotiation agenda (issues to negotiate about to avoid reporting the breaches).

sign_all_contracts(contracts)

Called to sign all contracts concluded in a single step by this agent

Parameters:

contracts (list[Contract]) – A list of contracts to sign/ refuse to sign

Returns:

None to indicate refusing to sign all contracts.
str (specifically, the agent ID) to indicate signing ALL contracts.
List[Optional[str]] A list with a value for each input contract where None means refusal to sign that contract and a string (agent ID) indicates acceptance to sign it. Note that in this case, the number of values in the returned list must match that of the contacts (and they should obviously correspond to the contracts).
Dict[str, Optional[str]] A mapping from contract ID to either a None for rejection to sign or a string (for acceptance to sign). Contracts with IDs not in the keys will assumed not to be signed.

Return type:

You can return any of the following

Remarks:

default implementation calls sign_contract for each contract returning the results

sign_contract(contract)

Called after the signing delay from contract conclusion to sign the contract. Contracts become binding only after they are signed.

Return type:: str | None

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

classmethod spawn_object(*args, **kwargs)

step()[source]: Override this method to modify stepping logic

step_(): Called at every time-step. This function is called directly by the world.