BaseElicitor

class negmas.elicitation.BaseElicitor(user: User, *, strategy: Optional[EStrategy] = None, base_negotiator: negmas.sao.negotiators.SAONegotiator = <negmas.sao.negotiators.AspirationNegotiator object>, opponent_model_factory: Optional[Callable[[AgentMechanismInterface], DiscreteAcceptanceModel]] = <function BaseElicitor.<lambda>>, expector_factory: Union[Expector, Callable[[], Expector]] = <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.sao.SAONegotiator

Attributes Summary

elicitation_cost

The total elicitation cost.

elicitation_time

The total elicitation time in seconds.

Methods Summary

accuracy_limit(cost)

The accuracy limit given the cost and epsilon.

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

elicit(state)

Called to do utility elicitation whenever needed.

elicit_single(state)

Does a single elicitation act

init_elicitation(ufun, **kwargs)

Called once to initialize the elicitation process

join(ami, state, *[, ufun, 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_negotiation_start(state)

Called when the negotiation starts.

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_response(state, partner_id, …)

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

propose(state)

Called to propose an outcome

respond_(state, offer)

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

user_ufun(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 UtilityDistribution 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

elicitation_cost

The total elicitation cost.

elicitation_time

The total elicitation time in seconds.

Methods Documentation

accuracy_limit(cost: float)float[source]

The accuracy limit given the cost and epsilon.

before_eliciting()None[source]

Called by apply just before continuously calling elicit_single

best_offer(state: negmas.common.MechanismState)Tuple[Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], float][source]

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

Parameters

state – The mechanism state

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.

abstract can_elicit()bool[source]

Returns whether we can do more elicitation

elicit(state: negmas.common.MechanismState)None[source]

Called to do utility elicitation whenever needed.

Parameters

state – 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.

abstract elicit_single(state: negmas.common.MechanismState)None[source]

Does a single elicitation act

Parameters

state – mechanism state

init_elicitation(ufun: Optional[Union[negmas.utilities.IPUtilityFunction, negmas.helpers.Distribution, List[negmas.helpers.Distribution]]], **kwargs)None[source]

Called once to initialize the elicitation process

Parameters
  • ufun – 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 UtilityDistribution is given as ufun, it is repeated for all outcomes (and the reserved value is set to zero).

  • If a list of UtilityDistribution 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

join(ami: negmas.common.AgentMechanismInterface, state: negmas.common.MechanismState, *, ufun: Optional[UtilityFunction] = None, role: str = 'agent', **kwargs)bool[source]

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

maximum_attainable_utility()float[source]

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

minimum_guaranteed_utility()[source]

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

offering_utilities(state)numpy.ndarray[source]

Calculates the offering utility for all outcomes

Parameters

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

Returns

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

Remarks:
offering_utility(outcome, state)Union[negmas.helpers.Distribution, float][source]

returns expected utlity of offering outcome in state

Parameters
  • outcome – The outcome

  • state – The state

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 UtilityDistribution, this method will return a UtilityDistribution not a real number.

on_negotiation_start(state: negmas.common.MechanismState)[source]

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

on_opponent_model_updated(outcomes: List[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]], old: List[float], new: List[float])None[source]

Called whenever an opponents model is updated.

Parameters
  • outcomes – A list of outcomes for which the acceptance probability are changed

  • old – The old acceptance probability

  • new – The new acceptance probability

on_partner_proposal(state: negmas.common.MechanismState, partner_id: str, offer: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]])[source]

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

Parameters
  • state – mechanism state

  • partner_id – the partner who proposed

  • offer – The offer from the partner

Remarks:
on_partner_response(state: negmas.common.MechanismState, partner_id: str, outcome: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], response: negmas.outcomes.ResponseType)[source]

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

Parameters
  • state – mechanism state

  • partner_id – the partner who offered

  • outcome – The outcome responded to

  • response – 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.

propose(state: negmas.common.MechanismState)Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]][source]

Called to propose an outcome

Parameters

state – mechanism state

Remarks:

  • if the negotiator can_elicit, it will elicit.

  • always then calls the base negotiator to propose.

respond_(state: negmas.common.MechanismState, offer: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]])negmas.outcomes.ResponseType[source]

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

Parameters
  • state – mechanism state

  • offer – the offer to respond to

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.

user_ufun(outcome: Optional[Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]]])float[source]

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

Parameters

outcome – 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

utilities_on_rejection(state: negmas.common.MechanismState)List[Union[negmas.helpers.Distribution, float]][source]

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()List[negmas.helpers.Distribution][source]

Returns a UtilityDistribution for every outcome

utility_on_acceptance(outcome: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]])Union[negmas.helpers.Distribution, float][source]

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

utility_on_rejection(outcome: Union[negmas.outcomes.OutcomeType, Tuple[Union[int, float, str, list]], Dict[Union[int, str], Union[int, float, str, list]]], state: negmas.common.MechanismState)Union[negmas.helpers.Distribution, float][source]

Estimated utility if this outcome rejected at this state.

Parameters
  • outcome – The outcome tested

  • state – The mechanism state

Remarks:
  • MUST be implemented by any Elicitor.