BaseVOIElicitor

class negmas.elicitation.BaseVOIElicitor(strategy, user, *, dynamic_query_set=False, queries=None, adaptive_answer_probabilities=True, each_outcome_once=False, update_related_queries=True, **kwargs)[source]

Bases: BaseElicitor

Base class for all value of information (VOI) elicitation algorithms

Parameters:

strategy (EStrategy) – The elicitation strategy. It is only used if dynamic_query_set is set. In that case, the strategy is used to compile the set of all possible queries during construction. If using dynamic_query_set pass None for the strategy.
user (User) – The User to elicit.
base_negotiator – The base negotiator used for proposing and responding.
dynamic_query_set – If given, the user of the object is supposed to manage the queries manually and the strategy is not used.
queries – An optinal list of queries to use.
adaptive_answer_probabilities – If True, answer probabilities will not be considered equal for all possible answers. The probability of getting an answer will be based on the current estimate of the utility value distribution.
expector_factory – A Callable used to estimate real-valued utilities given a distribution.
opponent_model_factory – A Callable used to construct the opponent model.
single_elicitation_per_round – If set, a single query is allowed per round.
continue_eliciting_past_reserved_val – If set, elicition will continue even if the estimated utility of an outcome is less than the reserved value.
epsilon – A small number used to stop elicitation when the uncertainty in the utility value is within it.
true_utility_on_zero_cost – If set, the true utility will be elicited for outcomes if the elicitation cost is zero.
each_outcome_once – If set, each outcome is to be offered exactly once.
update_related_queries – If set, queries that are related to one that was asked and answered will get updated based on the answer.

Attributes Summary

`ami`
`annotation`	Returns the private information (annotation) not shared with other negotiators
`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?
`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).
`nmi`
`opponent_ufun`
`owner`	Returns the owner agent of the negotiator
`parent`	Returns the parent controller
`preferences`	The utility function attached to that object
`private_info`	Returns the private information (annotation) not shared with other negotiators
`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`
`type_name`
`ufun`	Returns the preferences if it is a `BaseUtilityFunction` else None
`uuid`	The unique ID of this entity

Methods Summary

`__call__`(state)	Called by `Negotiator.__call__` (which is called by the mechanism) to counter the offer.
`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.
`add_query`(qeeu)	Adds a query to the heap of queries
`before_death`(cntxt)	Called whenever the parent is about to kill this negotiator.
`before_eliciting`()	Called every round before trying to elicit.
`best_offer`(state)	The best offer and its corresponding utility
`best_offers`(n)	Returns the best offer repeated n times
`can_elicit`()	Always can elicit
`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
`create`(args, *kwargs)	Creates an object and returns a proxy to it.
`elicit`(state)	Called to do utility elicitation whenever needed.
`elicit_single`(state)	Called to conduct a single eliciataion 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[, queries])	Initializes the elicitation process once.
`init_optimal_policy`()	Gets the optimal policy given Negotiator utility_priors.
`init_query_eeus`()	Updates the heap eeu_query which has records of (-EEU, quesion)
`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 the opponent model is updated.
`on_partner_ended`(partner)	Called when a partner ends the negotiation.
`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_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[, source])	Called to respond to an offer.
`respond_`(state, offer)	Called by the mechanism directly (through `counter` ) to respond to offers.
`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)
`update_optimal_policy`(index, outcome, oldu, newu)	Updates the optimal policy after a change to the utility value of some outcome.
`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

annotation: Returns the private information (annotation) not shared with other negotiators

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?

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

nmi

opponent_ufun

owner: Returns the owner agent of the negotiator

parent: Returns the parent controller

preferences: The utility function attached to that object

private_info: Returns the private information (annotation) not shared with other negotiators

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

type_name

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

uuid: The unique ID of this entity

Methods Documentation

__call__(state)

Called by Negotiator.__call__ (which is 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.
Returns:: The response to the given offer with a counter offer if the response is REJECT
Return type:: Tuple[ResponseType, Outcome]

Remarks:

The current offer is accessible through state.current_offer

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:

add_query(qeeu)[source]

Adds a query to the heap of queries

Parameters:: qeeu (tuple[float, int]) – A Tuple giving (-EEU, query_index)
Return type:: None

Remarks:

Note that the first member of the tuple is minus the EEU
The sedond member of the tuple is an index of the query in the queries list (not the query itself).

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()[source]: Called every round before trying to elicit. Does nothing

best_offer(state)[source]

The best offer and its corresponding utility

Parameters:: state (MechanismState) – The mechanism state
Return type:: tuple[tuple | None, float]

Remarks:

It will return (None, reserved-value) if the best outcome has a utility less than the reserved value.
It uses the internal eu_policy heap to find the best outcome.
If each-outcome-once is set, the best outcome is popped from the heap which prevents it from ever being selected again.

best_offers(n)[source]

Returns the best offer repeated n times

Return type:: list[tuple[tuple | None, float]]

can_elicit()[source]

Always can elicit

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

elicit(state)

Called to do utility elicitation whenever needed.

Parameters:: state (MechanismState) – mechanism state
Return type:: None

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.

elicit_single(state)[source]

Called to conduct a single eliciataion act.

Parameters:: state (MechanismState) – The mechanism state

Remarks:

It returns False ending eliciatation if eeu_query is empty or can_elicit returns False
The algorithm outline is as follows:
1. Pops the top query with its EEU from the heap
2. elicitation is stopped if the top query is None, the eeu is less than the current EEU, or the EEU after asking will be less than the reserved value.
3. If dynamic_query_set, the strategy is invoked to get the next query, otherwise, the user is asked the top query and the related queries are updated.
4. The expected utility is updated base on the answer received from the user and update_optimal_policy is called followed by init_query_eeus.

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

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, queries=None, **kwargs)[source]

Initializes the elicitation process once.

Return type:: None

Remarks:

After calling parent, it checks that dynamic_query_set, queries and strategy settings are consistent.
It then calls, init_optimal_policy to initialize the optimal policy
The set of queries is updated from the strategy if needed and a mapping from outcomes to their queries is created if update_related_queries is set to be used for updating related queries later.
It then calls init_query_eeus to initialize the EEU of all queries.

abstract init_optimal_policy()[source]

Gets the optimal policy given Negotiator utility_priors.

The optimal plicy should be sorted ascendingly on -EU or -EU * Acceptance

Return type:: None

init_query_eeus()[source]

Updates the heap eeu_query which has records of (-EEU, quesion)

Return type:: None

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.

Return type:: bool

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

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:

This is just a faster version of calling offering_utility in a loop.

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 (TypeVar(TState, bound= MechanismState)) – MechanismState giving current state of the negotiation.
Return type:: None

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

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 (TypeVar(TState, bound= MechanismState)) – MechanismState giving current state of the negotiation.
Return type:: None

Remarks:

The default behavior is to do nothing.
Override this to hook some action

on_negotiation_end(state)

A call back called at each negotiation end

Parameters:: state (TypeVar(TState, bound= MechanismState)) – MechanismState or one of its descendants giving the state at which the negotiation ended.
Return type:: None

Remarks:

The default behavior is to do nothing.
Override this to hook some action
on_negotiation_start and on_negotiation_end will always be called once for every agent.

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:

notification (Notification)
notifier (str)

Return type:

bool

Returns:

on_opponent_model_updated(outcomes, old, new)[source]

Called whenever the opponent model is updated.

Parameters:

outcomes (list[tuple]) – The updated outomes. None means all outcomes
old (list[float]) – The old acceptance probabilities
new (list[float]) – The new acceptance probabilities

Return type:

None

Remarks:: It calls init_optimal_policy and init_query_eeus if any old value is not equal to a new value.

on_partner_ended(partner)

Called when a partner ends the negotiation.

Note that the negotiator owning this component may never receive this offer. This is only receivd if the mechanism is sending notifications on every offer.

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:

Used to update the opponent model by calling update_offered then on_opponent_model_updated.

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 (TypeVar(TState, bound= MechanismState)) – MechanismState giving current state of the negotiation.
Return type:: None

Remarks:

The default behavior is to do nothing.
Override this to hook some action

on_round_start(state)

A call back called at each negotiation round start

Parameters:: state (TypeVar(TState, bound= MechanismState)) – MechanismState giving current state of the negotiation.
Return type:: None

Remarks:

The default behavior is to do nothing.
Override this to hook some action.

propose(state)

Called to propose an outcome

Parameters:: state (MechanismState) – mechanism state
Return type:: tuple

Remarks:

if the negotiator can_elicit, it will elicit.

always then calls the base negotiator to propose.

propose_(state)

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

Parameters:: state (SAOState) – The mechanism state
Return type:: tuple | 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, source=None)

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

Parameters:

state – a SAOState giving current state of the negotiation.
source (str | None) – The ID of the negotiator that gave this offer

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).
The current offer to respond to can be accessed through state.current_offer

respond_(state, offer)

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

Parameters:

state (MechanismState) – mechanism state
offer (tuple) – the offer to respond to

Return type:

ResponseType

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.

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

set_preferences(value, force=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:

None

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

classmethod spawn_object(*args, **kwargs)

update_optimal_policy(index, outcome, oldu, newu)[source]

Updates the optimal policy after a change to the utility value of some outcome.

Parameters:

outcome (tuple) – The outcome whose utiltiy have changed
oldu (float) – The old utility
newu (float) – The new utility

Remarks:: It just calls update_optimal_policy

user_preferences(outcome)

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

Parameters:: outcome (tuple | None) – The outcome to find the user utility for. If None, it returns the reserved value.
Return type:: float

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

utilities_on_rejection(state)

Finds the utility of rejection for all outputs.

Return type:: list[Union[Distribution, float]]

Remarks:

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

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:

outcome (tuple) – The outcome tested
state (MechanismState) – The mechanism state

Return type:

Union[Distribution, float]

Remarks:

MUST be implemented by any Elicitor.