DummyElicitor

class negmas.elicitation.DummyElicitor(user, *, strategy=None, base_negotiator=<negmas.sao.negotiators.timebased.AspirationNegotiator object>, opponent_model_factory=<function BaseElicitor.<lambda>>, expector_factory=<class 'negmas.elicitation.expectors.MeanExpector'>, single_elicitation_per_round=False, continue_eliciting_past_reserved_val=False, epsilon=0.001, true_utility_on_zero_cost=False)[source]

Bases: negmas.elicitation.base.BaseElicitor

A dummy elicitation algorithm that does not do any elicitation.

Attributes Summary

ami

rtype

NegotiatorMechanismInterface | None

capabilities

Agent capabilities

crisp_ufun

Returns the preferences if it is a CrispUtilityFunction else None

elicitation_cost

The total elicitation cost.

elicitation_time

The total elicitation time in seconds.

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

nmi

rtype

NegotiatorMechanismInterface | None

owner

Returns the owner agent of the negotiator

parent

Returns the parent controller

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

type_name

rtype

str

ufun

Returns the preferences if it is a UtilityFunction else None

uuid

The unique ID of this entity

Methods Summary

accuracy_limit(cost)

The accuracy limit given the cost and epsilon.

add_capabilities(capabilities)

Adds named capabilities to the negotiator.

add_handler(notification_type, callback)

Adds a notification handler to the list of handlers of the given type.

before_death(cntxt)

Called whenever the parent is about to kill this negotiator.

before_eliciting()

Called by apply just before continuously calling elicit_single

best_offer(state)

The outcome with maximum expected utility given the expector and its utility

can_elicit()

Returns whether we can do more elicitation

cancel([reason])

A method that may be called by a mechanism to make the negotiator cancel whatever it is currently processing.

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

counter(state, offer)

Called by the mechanism to counter the offer.

create(*args, **kwargs)

Creates an object and returns a proxy to it.

elicit(state)

Called to do utility elicitation whenever needed.

elicit_single(state)

Does a single elicitation act

from_checkpoint(file_name[, return_info])

Creates an object from a saved checkpoint

handlers(notification_type)

Gets the list of handlers registered for some notification type.

init_elicitation(preferences, **kwargs)

Called once to initialize the elicitation process

is_acceptable_as_agreement(outcome)

Whether the given outcome is acceptable as a final agreement of a negotiation.

isin(negotiation_id)

Is that agent participating in the given negotiation? Tests if the agent is participating in the given negotiation.

join(nmi, state, *[, preferences, role])

Called to join a negotiation.

maximum_attainable_utility()

Maximum utility that could even in principle be attained which simply means the utility value of the outcome with maximum utility.

minimum_guaranteed_utility()

Minimum utility that could even in principle be attained which simply means the utility value of the outcome with minimum utility.

offering_utilities(state)

Calculates the offering utility for all outcomes

offering_utility(outcome, state)

returns expected utlity of offering outcome in state

on_leave(state)

A call back called after leaving a negotiation.

on_mechanism_error(state)

A call back called whenever an error happens in the mechanism.

on_negotiation_end(state)

A call back called at each negotiation end

on_negotiation_start(state)

Called when the negotiation starts.

on_notification(notification, notifier)

Called whenever a notification is received

on_notification_(notification, notifier)

Called when a notification is received.

on_opponent_model_updated(outcomes, old, new)

Called whenever an opponents model is updated.

on_partner_proposal(state, partner_id, offer)

Called when one of the partners propose (only if enable_callbacks is set in the SAOMechanism).

on_partner_refused_to_propose(state, partner_id)

A callback called by the mechanism when a partner refuses to propose

on_partner_response(state, partner_id, ...)

Called when one of the partners respond (only if enable_callbacks is set in the SAOMechanism).

on_preferences_changed(changes)

Called to inform the entity that its ufun has changed.

on_round_end(state)

A call back called at each negotiation round end

on_round_start(state)

A call back called at each negotiation round start

propose(state)

Called to propose an outcome

propose_(state)

The method directly called by the mechanism (through counter ) to ask for a proposal

remove_capability(name)

Removes named capability from the negotiator

remove_handler(notification_type, callback)

Removes a notification handler from the list of handlers of the given type.

respond(state, offer)

Called to respond to an offer.

respond_(state, offer)

Called by the mechanism directly (through counter ) to respond to offers.

set_preferences(value[, force])

Sets tha utility function/Preferences.

spawn([spawn_as, spawn_params])

spawn_object(*args, **kwargs)

user_preferences(outcome)

Finds the total utility obtained by the user for this outcome after discounting elicitation cost.

utilities_on_rejection(state)

Finds the utility of rejection for all outputs.

utility_distributions()

Returns a Distribution for every outcome

utility_on_acceptance(outcome)

The utility of acceptance which is simply the utility function applied to outcome.

utility_on_rejection(outcome, state)

Estimated utility if this outcome rejected at this state.

Attributes Documentation

ami
Return type

NegotiatorMechanismInterface | None

capabilities

Agent capabilities

Return type

Dict[str, Any]

crisp_ufun

Returns the preferences if it is a CrispUtilityFunction else None

Return type

UtilityFunction | None

elicitation_cost

The total elicitation cost.

Return type

float

elicitation_time

The total elicitation time in seconds.

Return type

float

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

nmi
Return type

NegotiatorMechanismInterface | None

owner

Returns the owner agent of the negotiator

Return type

Agent | None

parent

Returns the parent controller

Return type

Controller | None

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

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

accuracy_limit(cost)

The accuracy limit given the cost and epsilon.

Return type

float

add_capabilities(capabilities)

Adds named capabilities to the negotiator.

Parameters

capabilities (dict) – The capabilities to be added as a dict

Return type

None

Returns

None

Remarks:

It is the responsibility of the caller to be really capable of added capabilities.

add_handler(notification_type, callback)

Adds a notification handler to the list of handlers of the given type. These handlers will be called in the order in which they are received

Parameters

  • notification_type (str) – Notification type as specificed in the type member of the Notification class

  • callback (Callable[[Notification, str], bool]) – The callback which must receive a Notification object and a string and returns a boolean. If True is returned from one callback, the remaining callbacks will not be called

Returns:

before_death(cntxt)

Called whenever the parent is about to kill this negotiator.

It should return False if the negotiator does not want to be killed but the controller can still force-kill it

Return type

bool

before_eliciting()

Called by apply just before continuously calling elicit_single

Return type

None

best_offer(state)

The outcome with maximum expected utility given the expector and its utility

Parameters

state (MechanismState) – The mechanism state

Return type

Tuple[Optional[tuple], float]

Returns

A tuple containing the best outcome (or None) and its expected utility using the expector (or reserved value)

Remarks:

  • if there are no offerable outcomes, elicitation is done and if still there are no offerable outcomes, the reserved value is returned (with None as outcome)

  • Only offerable outcomes are checked.

  • The best outcome is defined as the one with maximum expect applied to offering_utility.

can_elicit()[source]

Returns whether we can do more elicitation

Return type

bool

cancel(reason=None)

A method that may be called by a mechanism to make the negotiator cancel whatever it is currently processing.

Negotiators can just ignore this message (default behavior) but if there is a way to actually cancel work, it should be implemented here to improve the responsiveness of the negotiator.

Return type

None

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]

counter(state, offer)

Called by the mechanism to counter the offer. It just calls respond_ and propose_ as needed.

Parameters

  • state (SAOState) – SAOState giving current state of the negotiation.

  • offer (Outcome | None) – The offer to be countered. None means no offer and the agent is requested to propose an offer

Returns

The response to the given offer with a counter offer if the response is REJECT

Return type

Tuple[ResponseType, Outcome]

classmethod create(*args, **kwargs)

Creates an object and returns a proxy to it.

elicit(state)

Called to do utility elicitation whenever needed.

Parameters

state (MechanismState) – mechanism state

Remarks:

  • Keeps track of elicitation time and asking time.

  • If the maximum attainable utility minus elicitation cost is less than the reserved value, no elicitation will take place because we will end this negotiation anyway. Note that the maximum attainable utility can never go up.

  • Calls before_eliciting once to initialize the process then calls elicit_single which does the actual elicitation. This is done only once if single_elicitation is set, otherwise it is repeated until one of the following conditiosn is met:

    • elicit_single returns False

    • The maximum attainable utility (minus elicitation cost) is less than the reserved value.

Return type

None

elicit_single(state)[source]

Does a single elicitation act

Parameters

state (MechanismState) – mechanism state

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

handlers(notification_type)

Gets the list of handlers registered for some notification type. This list can be modified in place to change the order of handlers for example. It is NOT a copy.

Return type

List[Callable[[Notification, str], bool]]

init_elicitation(preferences, **kwargs)[source]

Called once to initialize the elicitation process

Parameters

  • preferences (Optional[Union['IPUtilityFunction', 'Distribution']]) – The probabilistic utility function

  • **kwargs –

Remarks:

  • If no ufun is given one will be created with 0-1 uniform distributions and zero reserved value.

  • If a single Distribution is given as ufun, it is repeated for all outcomes (and the reserved value is set to zero).

  • If a list of Distribution s is given, it must have the same length as the list of outcomes of this negotiation and is used to set the ufun.

  • The opponent model

is_acceptable_as_agreement(outcome)

Whether the given outcome is acceptable as a final agreement of a negotiation.

The default behavior is to reject only if a reserved value is defined for the agent and is known to be higher than the utility of the outcome.

Return type

bool

isin(negotiation_id)

Is that agent participating in the given negotiation? Tests if the agent is participating in the given negotiation.

Parameters

negotiation_id (Optional[str]) – The negotiation ID tested. If None, it means ANY negotiation

Returns

True if participating in the given negotiation (or any

negotiation if it was None)

Return type

bool

join(nmi, state, *, preferences=None, role='negotiator', **kwargs)

Called to join a negotiation.

Remarks:

  • uses the base_negotiator to join the negotiation.

  • creates a MappingUtilityFunction that maps every outcome to the result of the expector applied to the corresponding utility value.

  • The reserved value of the created ufun is set to -inf

Return type

bool

maximum_attainable_utility()

Maximum utility that could even in principle be attained which simply means the utility value of the outcome with maximum utility.

Return type

float

minimum_guaranteed_utility()

Minimum utility that could even in principle be attained which simply means the utility value of the outcome with minimum utility.

offering_utilities(state)

Calculates the offering utility for all outcomes

Parameters

state – Calculates the state at which the offering utilities are to be calculated

Return type

ndarray

Returns

An ndarray with the offering utility of every outcome (in order)

Remarks:
offering_utility(outcome, state)

returns expected utlity of offering outcome in state

Parameters

  • outcome – The outcome

  • state – The state

Return type

Union[Distribution, float]

Returns

A utility value

Remarks:

  • returns $u(o) p(o) + ru(o) (1-p(o))$ where $p$ is the opponent model, $u$ is the utility function, and $r$ is the utility in case of rejections.

  • state is needed when calculating $r(o)$ by calling utility_on_rejection.

  • Note that if $u$ or $r$ return a Distribution, this method will return a Distribution not a real number.

on_leave(state)

A call back called after leaving a negotiation.

Parameters

state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

  • MUST call the baseclass on_leave using super () if you are going to override this.

  • The default behavior is to do nothing.

  • Override this to hook some action

Return type

None

on_mechanism_error(state)

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

Parameters

state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

  • The default behavior is to do nothing.

  • Override this to hook some action

Return type

None

on_negotiation_end(state)

A call back called at each negotiation end

Parameters

state (MechanismState) – MechanismState or one of its descendants giving the state at which the negotiation ended.

Remarks:
Return type

None

on_negotiation_start(state)

Called when the negotiation starts. Just passes the call to base_negotiator.

on_notification(notification, notifier)

Called whenever a notification is received

Parameters

  • notification (Notification) – The notification

  • notifier (str) – The notifier entity

Remarks:

  • The default implementation only responds to end_negotiation by ending the negotiation

on_notification_(notification, notifier)

Called when a notification is received. Do NOT directly override this method

Parameters

Returns:

Return type

bool

on_opponent_model_updated(outcomes, old, new)

Called whenever an opponents model is updated.

Parameters

  • outcomes (List[tuple]) – A list of outcomes for which the acceptance probability are changed

  • old (List[float]) – The old acceptance probability

  • new (List[float]) – The new acceptance probability

Return type

None

on_partner_proposal(state, partner_id, offer)

Called when one of the partners propose (only if enable_callbacks is set in the SAOMechanism).

Parameters

  • state (MechanismState) – mechanism state

  • partner_id (str) – the partner who proposed

  • offer (tuple) – The offer from the partner

Remarks:
on_partner_refused_to_propose(state, partner_id)

A callback called by the mechanism when a partner refuses to propose

Parameters

  • state (SAOState) – SAOState giving the state of the negotiation when the partner refused to offer.

  • partner_id (str) – The ID of the agent who refused to propose

Remarks:

  • Will only be called if enable_callbacks is set for the mechanism

Return type

None

on_partner_response(state, partner_id, outcome, response)

Called when one of the partners respond (only if enable_callbacks is set in the SAOMechanism).

Parameters

  • state (MechanismState) – mechanism state

  • partner_id (str) – the partner who offered

  • outcome (tuple) – The outcome responded to

  • response (ResponseType) – The partner response including both the response and outcome

Remarks:

  • Used to update the opponent model by calling update_rejected or update_accepted1 then `on_opponent_model_updated.

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(state)

A call back called at each negotiation round end

Parameters

state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

  • The default behavior is to do nothing.

  • Override this to hook some action

Return type

None

on_round_start(state)

A call back called at each negotiation round start

Parameters

state (MechanismState) – MechanismState giving current state of the negotiation.

Remarks:

  • The default behavior is to do nothing.

  • Override this to hook some action.

Return type

None

propose(state)

Called to propose an outcome

Parameters

state (MechanismState) – mechanism state

Remarks:

  • if the negotiator can_elicit, it will elicit.

  • always then calls the base negotiator to propose.

Return type

tuple

propose_(state)

The method directly called by the mechanism (through counter ) to ask for a proposal

Parameters

state (SAOState) – The mechanism state

Return type

Outcome | None

Returns

An outcome to offer or None to refuse to offer

Remarks:

  • Depending on the SAOMechanism settings, refusing to offer may be interpreted as ending the negotiation

  • The negotiator will only receive this call if it has the ‘propose’ capability.

remove_capability(name)

Removes named capability from the negotiator

Parameters

capabilities – The capabilities to be added as a dict

Return type

None

Returns

None

Remarks:

It is the responsibility of the caller to be really capable of added capabilities.

remove_handler(notification_type, callback)

Removes a notification handler from the list of handlers of the given type.

Parameters

  • notification_type (str) – Notification type as specificed in the type member of the Notification class

  • callback (Callable[[Notification, str], bool]) – The callback which must receive a Notification object and a string and returns a boolean. If True is returned from one callback, the remaining callbacks will not be called

Return type

bool

Returns

Whether or not the handler was in the list of handlers for this type. In all cases, the handler will not be called after this call (either it was not there or it will be removed).

respond(state, offer)

Called to respond to an offer. This is the method that should be overriden to provide an acceptance strategy.

Parameters

  • state (SAOState) – a SAOState giving current state of the negotiation.

  • offer (tuple) – offer being tested

Returns

The response to the offer

Return type

ResponseType

Remarks:

  • The default implementation never ends the negotiation

  • The default implementation asks the negotiator to propose`() and accepts the `offer if its utility was at least as good as the offer that it would have proposed (and above the reserved value).

respond_(state, offer)

Called by the mechanism directly (through counter ) to respond to offers.

Parameters
Remarks:

  • Does the following steps:

    1. Finds the the best offer using best_offer and uses the base negotiator to respond if that offer was None

    2. Looks at offerable_outcomes and applies the elicitation strategy (one step) to the outcome if it was not offerable (or if there are no offerable outcomes defined).

    3. Finds the utility of the offer using utility_function not taking into accout elicitation cost and uses the base negotiator if that fails (i.e. utility_function returns None).

    4. Finds the expected utility of the offer using the expect () method which calls the expector passed during construction.

    5. If the maximum attainable utility now (judging from the current estimation of the utility value of each outcome taking elicitation cost into account) is less than the reserved value, end the negotiation

    6. If the utility of my best offer (returned from best_offer) is less than the offered utility, accept the offer

    7. Otherwise, call bhe base negotiator to respond.

Return type

ResponseType

set_preferences(value, force=False)

Sets tha utility function/Preferences.

Parameters

  • value (Preferences) – 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)
user_preferences(outcome)

Finds the total utility obtained by the user for this outcome after discounting elicitation cost.

Parameters

outcome (Optional[tuple]) – The outcome to find the user utility for. If None, it returns the reserved value.

Remarks:

The total elicitation cost is not discounted from the reserved value when the input is None

Return type

float

utilities_on_rejection(state)

Finds the utility of rejection for all outputs.

Remarks:

  • By default it calls utility_on_rejection repeatedly for all outcomes. Override this method if a faster versin can be implemented

Return type

List[Union[Distribution, float]]

utility_distributions()

Returns a Distribution for every outcome

Return type

List[ScipyDistribution]

utility_on_acceptance(outcome)

The utility of acceptance which is simply the utility function applied to outcome.

Return type

Union[Distribution, float]

utility_on_rejection(outcome, state)[source]

Estimated utility if this outcome rejected at this state.

Parameters
Remarks:

  • MUST be implemented by any Elicitor.

Return type

Union[Distribution, float]