VOINoUncertaintyElicitor
- class negmas.elicitation.VOINoUncertaintyElicitor(strategy, user, *, dynamic_query_set=False, queries=None, adaptive_answer_probabilities=True, each_outcome_once=False, update_related_queries=True, **kwargs)[source]
Bases:
BaseVOIElicitor
A dummy VOI Elicitation Agent. It simply assumes no uncertainty in own utility function
Attributes Summary
Returns the private information (annotation) not shared with other negotiators
Agent capabilities
Returns the preferences if it is a CrispUtilityFunction else None
The total elicitation cost.
The total elicitation time in seconds.
Does the entity has an associated ufun?
Does the entity has an associated ufun?
Does the entity has an associated ufun?
The unique ID of this entity
A convenient name of the entity (intended primarily for printing/logging/debugging).
Returns the owner agent of the negotiator
Returns the parent controller
The utility function attached to that object
Returns the private information (annotation) not shared with other negotiators
Returns the preferences if it is a ProbUtilityFunction else None
Reserved outcome is the outcome that will be realized by default for this agent.
Reserved value is what the entity gets if no agreement is reached in the negotiation.
Returns the preferences if it is a
BaseUtilityFunction
else NoneThe 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.
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
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.
eeu
(policy, eup)Expected Expected Negotiator for following the policy
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.
Gets the optimal policy given Negotiator utility_priors
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 utility that could even in principle be attained which simply means the utility value of the outcome with maximum 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)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 proposalremove_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.
Returns a
Distribution
for every outcomeutility_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 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 callsrespond_
andpropose_
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
- add_capabilities(capabilities)
Adds named capabilities to the negotiator.
- Parameters:
capabilities (
dict
) – The capabilities to be added as a dict- Return type:
- 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 classcallback (
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
- 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:
- before_eliciting()
Called every round before trying to elicit. Does nothing
- best_offer(state)
The best offer and its corresponding utility
- Parameters:
state (
MechanismState
) – The mechanism state- Return type:
- 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)
Returns the best offer repeated n times
- 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:
- 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 checkpointfile_name (
str
|None
) – Name of the file to dump into. If not given, a unique name is createdinfo (
dict
[str
,Any
] |None
) – Information to save with the checkpoint (must be json serializable)exist_ok (
bool
) – If true, override existing dumpsingle_checkpoint (
bool
) – If true, keep a single checkpoint for the last stepstep_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:
- 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
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:
- 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 callselicit_single
which does the actual elicitation. This is done only once ifsingle_elicitation
is set, otherwise it is repeated until one of the following conditiosn is met:elicit_single
returns FalseThe 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 FalseThe algorithm outline is as follows:
Pops the top query with its EEU from the heap
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.
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.
The expected utility is updated base on the answer received from the user and
update_optimal_policy
is called followed byinit_query_eeus
.
- classmethod from_checkpoint(file_name, return_info=False)
Creates an object from a saved checkpoint
- Parameters:
- Return type:
- 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)
Initializes the elicitation process once.
- Return type:
None
- Remarks:
After calling parent, it checks that
dynamic_query_set
,queries
andstrategy
settings are consistent.It then calls,
init_optimal_policy
to initialize the optimal policyThe 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.
- init_query_eeus()[source]
Updates the heap eeu_query which has records of (-EEU, quesion)
- Return type:
- 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:
- 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=None, role='negotiator', **kwargs)
Called to join a negotiation.
- Return type:
- 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:
- 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:
- 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
instate
- Parameters:
outcome – The outcome
state – The state
- Return type:
- 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 callingutility_on_rejection
.Note that if $u$ or $r$ return a
Distribution
, this method will return aDistribution
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:
- 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:
- 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:
- Remarks:
The default behavior is to do nothing.
Override this to hook some action
on_negotiation_start
andon_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 notificationnotifier (
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:
Returns:
- on_opponent_model_updated(outcomes, old, new)
Called whenever the opponent model is updated.
- Parameters:
- Return type:
- Remarks:
It calls
init_optimal_policy
andinit_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 statepartner_id (
str
) – the partner who proposedoffer (
tuple
) – The offer from the partner
- Remarks:
Used to update the opponent model by calling
update_offered
thenon_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 statepartner_id (
str
) – the partner who offeredoutcome (
tuple
) – The outcome responded toresponse (
ResponseType
) – The partner response including both the response and outcome
- Remarks:
Used to update the opponent model by calling
update_rejected
orupdate_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:
- 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:
- 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:
Remarks:
if the negotiator
can_elicit
, it willelicit
.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:
- 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 negotiationThe 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:
- 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 classcallback (
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:
- 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:
- Returns:
The response to the offer
- Return type:
- 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 stateoffer (
tuple
) – the offer to respond to
- Return type:
- Remarks:
Does the following steps:
Finds the the best offer using
best_offer
and uses the base negotiator to respond if that offer wasNone
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).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
returnsNone
).Finds the expected utility of the offer using the
expect
() method which calls the expector passed during construction.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
If the utility of my best offer (returned from
best_offer
) is less than the offered utility, accept the offerOtherwise, 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 toforce – If true,
on_preferecnes_changed()
will always be called even ifvalue
==self.preferences
- Return type:
- classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)
- classmethod 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.
- Parameters:
- 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:
- 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.
- 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
.
- utility_on_rejection(outcome, state)
Estimated utility if this outcome rejected at this state.
- Parameters:
outcome (
tuple
) – The outcome testedstate (
MechanismState
) – The mechanism state
- Return type:
- Remarks:
MUST be implemented by any Elicitor.