negmas.negotiators

This module defines the interfaces to all negotiation agents (negotiators) in negmas.

class negmas.negotiators.Aspiration(*args, **kwargs)[source]

Bases: TimeCurve, Protocol

A monotonically decreasing time-curve

abstractmethod utility_at(t: float) → float[source]

Utility at.

Parameters:

t –

Returns:

The result.

Return type:

float

utility_range(t: float) → tuple[float, float][source]

Utility range.

Parameters:

t –

Returns:

The result.

Return type:

tuple[float, float]

class negmas.negotiators.BinaryComparatorNegotiator(*args, **kwargs)[source]

Bases: Negotiator

A negotiator that can be asked to compare two outcomes using is_better. By default is just consults the ufun.

To change that behavior, override is_better.

It has the compare-binary capability.

is_better(first: Outcome | None, second: Outcome | None, epsilon: float = 1e-10) → bool | None[source]

Compares two offers using the ufun returning whether the first is better than the second

Parameters:

  • first – First outcome to be compared

  • second – Second outcome to be compared

  • epsilon – comparison threshold. If the utility difference within the range [-epsilon, epsilon] the two outcomes are assumed to be compatible

Returns:

True if utility(first) > utility(second) + epsilon, None if the absolute difference is <= epsilon or the ufun is not defined, False if utility(first) < utility(second) - epsilon.

class negmas.negotiators.Component(negotiator: Negotiator)[source]

Bases: object

A component that can be added to a ModularNegotiator

after_join(nmi: NegotiatorMechanismInterface) → None[source]

A call back called after joining a negotiation to confirm wwe joined.

can_join(nmi: NegotiatorMechanismInterface, state: MechanismState, *, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, role: str = 'negotiator') → bool[source]

A call back called before joining a negotiation to confirm that we can join it.

property negotiator[source]

Returns the negotiator this component is attached to.

on_leave(state: MechanismState) → None[source]

A call back called after leaving a negotiation.

on_mechanism_error(state: MechanismState) → None[source]

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

on_negotiation_end(state: MechanismState) → None[source]

A call back called at each negotiation end

on_negotiation_start(state: MechanismState) → None[source]

A call back called at each negotiation start

on_preferences_changed(changes: list[PreferencesChange])[source]

Called to inform the component that the ufun has changed and the kinds of change that happened.

on_round_end(state: MechanismState) → None[source]

A call back called at each negotiation round end

on_round_start(state: MechanismState) → None[source]

A call back called at each negotiation round start

set_negotiator(negotiator: Negotiator) → None[source]

Sets the negotiator of which this component is a part.

class negmas.negotiators.ControlledNegotiator(name: str | None = None, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, parent: Controller | None = None, owner: Agent | None = None, id: str | None = None, type_name: str | None = None, private_info: dict[str, Any] | None = None)[source]

Bases: Negotiator

A negotiator that can be used to pass all method calls to a parent (Controller).

It uses magic dunder methods to implement a general way of passing calls to the parent. This method is slow.

It is recommended to implement a ControlledNegotiator for each mechanism that does this passing explicitly which will be much faster.

For an example, see the implementation of ControlledSAONegotiator .

class negmas.negotiators.Controller(default_negotiator_type: str | TControlledNegotiator | None = None, default_negotiator_params: dict[str, Any] | None = None, parent: Controller | Agent | None = None, auto_kill: bool = True, **kwargs)[source]

Bases: Rational, Generic[TNMI, TState, TControlledNegotiator]

Controls the behavior of multiple negotiators in multiple negotiations.

The controller class MUST implement any methods of the negotiator class it is controlling with one added argument negotiator_id (str) which represents ID of the negotiator on which the method is being invoked (passed first).

Controllers for specific classes should inherit from this class and implement whatever methods they want to override on their ControlledNegotiator objects. For example, the SAO module defines SAOController that needs only to implement propose and respond .

Parameters:

  • default_negotiator_type – The negotiator type to use for adding negotiator if no type is explicitly given.

  • default_negotiator_params – The parameters to use to construct the default negotiator type.

  • parent – The parent which can be an Agent or another Controller

  • auto_kill – If True, negotiators will be killed once their negotiation finishes.

  • name – The controller name

Remarks:

  • Controllers should always call negotiator methods using the call method defined in this class. Direct calls may lead to infinite loops

property active_negotiators: dict[str, NegotiatorInfo][source]

Returns the negotiators whose negotiations running or did not start yet.

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context

add_negotiator(negotiator: Negotiator, cntxt: Any = None) → None[source]

Adds a negotiator to the controller.

Parameters:

  • negotaitor – The negotaitor to add

  • name – negotiator name

  • cntxt – The context to be associated with this negotiator.

  • **kwargs – any key-value pairs to be passed to the negotiator constructor

after_join(negotiator_id: str, nmi: TNMI, state: TState, *, preferences: Preferences | None = None, role: str = 'negotiator') → None[source]

Called by children negotiators after joining a negotiation to inform the controller

Parameters:

  • negotiator_id – The negotiator ID

  • nmi (AgentMechanismInterface) – The negotiation.

  • state (TState) – The current state of the negotiation

  • preferences (UtilityFunction) – The ufun function to use before any discounting.

  • role (str) – role of the agent.

before_join(negotiator_id: str, nmi: TNMI, state: TState, *, preferences: Preferences | None = None, role: str = 'negotiator') → bool[source]

Called by children negotiators to get permission to join negotiations

Parameters:

  • negotiator_id – The negotiator ID

  • nmi (AgentMechanismInterface) – The negotiation.

  • state (TState) – The current state of the negotiation

  • preferences (UtilityFunction) – The prefrences to use before any discounting.

  • role (str) – role of the agent.

Returns:

True if the negotiator is allowed to join the negotiation otherwise False

call(negotiator: ControlledNegotiator, method: str, *args, **kwargs)[source]

Calls the given method on the given negotiator safely without causing recursion. The controller MUST use this function to access any callable on the negotiator.

Parameters:

  • negotiator

  • method

  • *args

  • **kwargs

Returns:

create_negotiator(negotiator_type: str | TControlledNegotiator | None = None, name: str | None = None, cntxt: Any = None, **kwargs) → TControlledNegotiator[source]

Creates a negotiator passing it the context

Parameters:

  • negotiator_type – Type of the negotiator to be created

  • name – negotiator name

  • cntxt – The context to be associated with this negotiator.

  • **kwargs – any key-value pairs to be passed to the negotiator constructor

Returns:

The negotiator to be controlled. None for failure

property default_negotiator_type[source]

Default negotiator type.

property finished_negotiators: dict[str, NegotiatorInfo][source]

Returns the negotiators whose negotiations started and completed

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context

is_clean() → bool[source]

Checks that the agent has no negotiators and that all its intermediate data-structures are reset

join(negotiator_id: str, nmi: TNMI, state: TState, *, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, role: str = 'negotiator') → bool[source]

Called by the mechanism when the agent is about to enter a negotiation. It can prevent the agent from entering

Parameters:

  • negotiator_id – The negotiator ID

  • nmi (AgentMechanismInterface) – The negotiation.

  • state (TState) – The current state of the negotiation

  • preferences (Preferences) – The preferences.

  • ufun (BaseUtilityFunction) – The ufun function to use before any discounting (overrides preferences)

  • role (str) – role of the agent.

Returns:

bool indicating whether or not the agent accepts to enter.If False is returned it will not enter the negotiation.

kill_negotiator(negotiator_id: str, force: bool = False) → None[source]

Kills the negotiator sending it an before_death message.

Parameters:

  • negotiator_id – The ID of the negotiator to kill.

  • force – Whether to kill the negotiator in case it refused to die.

Remarks:

  • Killing a negotiator amounts to nothing more than removing it form the list of negotiators maintained by the controller.

make_negotiator(negotiator_type: str | TControlledNegotiator | None = None, name: str | None = None, **kwargs) → TControlledNegotiator[source]

Creates a negotiator but does not add it to the controller. Call add_negotiator to add it.

Parameters:

  • negotiator_type – Type of the negotiator to be created. If None, A ControlledNegotiator negotiator will be controlled (which is fully controlled by the controller).

  • name – negotiator name

  • **kwargs – any key-value pairs to be passed to the negotiator constructor

Returns:

The negotiator to be controlled. None for failure

property negotiators: dict[str, NegotiatorInfo][source]

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context.

on_leave(negotiator_id: str, state: TState) → None[source]

A call back called after leaving a negotiation.

Parameters:

  • negotiator_id – The negotiator ID

  • state – TState giving current state of the negotiation.

on_mechanism_error(negotiator_id: str, state: TState) → None[source]

On mechanism error.

Parameters:

  • negotiator_id – Negotiator id.

  • state – Current state.

on_negotiation_end(negotiator_id: str, state: TState) → None[source]

A call back called at each negotiation end

Parameters:

  • negotiator_id – The negotiator ID

  • state – TState or one of its descendants giving the state at which the negotiation ended.

on_negotiation_start(negotiator_id: str, state: TState) → None[source]

A call back called at each negotiation start

Parameters:

  • negotiator_id – The negotiator ID

  • state – TState giving current state of the negotiation.

on_notification(negotiator_id: str, notification: Notification, notifier: str)[source]

On notification.

Parameters:

  • negotiator_id – Negotiator id.

  • notification – Notification.

  • notifier – Notifier.

on_round_end(negotiator_id: str, state: TState) → None[source]

A call back called at each negotiation round end

Parameters:

  • negotiator_id – The negotiator ID

  • state – TState giving current state of the negotiation.

on_round_start(negotiator_id: str, state: TState) → None[source]

A call back called at each negotiation round start

Parameters:

  • negotiator_id – The negotiator ID

  • state – TState giving current state of the negotiation.

partner_agent_ids(negotiator_id: str) → list[str] | None[source]

Finds the agent ID negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

partner_agent_names(negotiator_id: str) → list[str] | None[source]

Finds the negotiator names negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

partner_negotiator_ids(negotiator_id: str) → list[str] | None[source]

Finds the negotiator ID negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

partner_negotiator_names(negotiator_id: str) → list[str] | None[source]

Finds the negotiator names negotiating with one of our negotiators.

Parameters:

negotiator_id – Our negotiator ID

reset()[source]

Resets the controller and kills any negotiators it may have

property started_negotiators: dict[str, NegotiatorInfo][source]

Returns the negotiators whose negotiations started

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context

property states: dict[str, TState][source]

Gets the current states of all negotiations as a mapping from negotiator ID to mechanism.

property to_start_negotiators: dict[str, NegotiatorInfo][source]

Returns the negotiators whose negotiations did not start yet

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context

property unfinished_negotiators: dict[str, NegotiatorInfo][source]

Returns the negotiators whose negotiations started and did not complete yet

Returns a dictionary mapping negotiator ID to the a tuple containing the negotiator and its context

class negmas.negotiators.EvaluatorNegotiator(*args, **kwargs)[source]

Bases: Negotiator

A negotiator that can be asked to evaluate outcomes using its internal ufun.

Th change the way it evaluates outcomes, override evaluate.

It has the evaluate capability

evaluate(outcome: Outcome) → Value | None[source]

Evaluates the given outcome using the internal utility function.

class negmas.negotiators.ExpAspiration(max_aspiration: float, aspiration_type: Literal['boulware'] | Literal['conceder'] | Literal['linear'] | float)[source]

Bases: Aspiration

An exponential conceding curve

Parameters:

  • max_aspiration – The aspiration level to start from (usually 1.0)

  • aspiration_type – The aspiration type. Can be a string (“boulware”, “linear”, “conceder”) or a number giving the exponent of the aspiration curve.

utility_at(t: float) → float[source]

The aspiration level

Parameters:

t – relative time (a number between zero and one)

Returns:

aspiration level

class negmas.negotiators.ModularNegotiator(*args, components: Iterable[Component], component_names: Iterable[str] | None = None, **kwargs)[source]

Bases: Negotiator

A generic modular negotiator that can combine multiple negotiation Component s.

This class simply holds a list of components and call them on every event.

property components: tuple[Component, ...][source]

Components.

Returns:

The result.

Return type:

tuple[Component, …]

insert_component(component: Component, name: str | None = None, index: int = -1, override: bool = False) → None[source]

Adds a component at the given index. If a negative number is given, appends at the end

join(nmi: NegotiatorMechanismInterface, state: MechanismState, *, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, role: str = 'negotiator') → bool[source]

Join.

Parameters:

  • nmi – Nmi.

  • state – Current state.

Returns:

The result.

Return type:

bool

on_leave(state: MechanismState) → None[source]

A call back called after leaving a negotiation.

on_mechanism_error(state: MechanismState) → None[source]

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

on_negotiation_end(state: MechanismState) → None[source]

A call back called at each negotiation end

on_negotiation_start(state: MechanismState) → None[source]

A call back called at each negotiation start

on_preferences_changed(changes: list[PreferencesChange])[source]

Called to inform the component that the ufun has changed and the kinds of change that happened.

on_round_end(state: MechanismState) → None[source]

A call back called at each negotiation round end

on_round_start(state: MechanismState) → None[source]

A call back called at each negotiation round start

remove_component(name: str) → None[source]

Removes the component with the given name

remove_component_at(index: int) → None[source]

Removes the component at the givne index.

class negmas.negotiators.NLevelsComparatorNegotiator(*args, thresholds: list[float] | None = None, **kwargs)[source]

Bases: Negotiator

A negotiator that can be asked to compare two outcomes using compare_nlevels which returns the strength of the difference between two outcomes as an integer from [-n, n] in the C compare sense. By default is just consults the ufun.

To change that behavior, override compare_nlevels.

It has the compare-nlevels capability.

compare_nlevels(first: Outcome, second: Outcome, n: int = 2) → int | None[source]

Compares two offers using the ufun returning an integer in [-n, n] (i.e. 2n+1 possible values) which defines which outcome is better and the strength of the difference (discretized using internal thresholds)

Parameters:

  • first – First outcome to be compared

  • second – Second outcome to be compared

  • n – number of levels to use

Returns:

  • None if either there is no ufun defined or the number of thresholds required cannot be satisfied

  • 0 if abs(u(first) - u(second)) <= thresholds[0]

  • -i if -thresholds[i-1] < u(first) - u(second) <= -thresholds[i]

  • +i if thresholds[i-1] > u(first) - u(second) >= thresholds[i]

Remarks:

  • thresholds is an internal array that can be set using thresholds property

  • thresholds[n] is assumed to equal infinity

  • n must be <= the length of the internal thresholds array. If n > that length, a ValueError will be raised. If n < the length of the internal thresholds array, the first n values of the array will be used

classmethod equiprobable_thresholds(n: int, preferences: Preferences, issues: list[Issue], n_samples: int = 1000) → list[float][source]

Generates thresholds for the n given levels where levels are equally likely approximately

Parameters:

  • n – Number of scale levels (one side)

  • preferences – The utility function to use

  • issues – The issues to generate the thresholds for

  • n_samples – The number of samples to use during the process

classmethod generate_thresholds(n: int, ufun_min: float = 0.0, ufun_max: float = 1.0, scale: str | Callable[[float], float] | None = None) → list[float][source]

Generates thresholds for the n given levels assuming the ufun ranges and scale function

Parameters:

  • n – Number of scale levels (one side)

  • ufun_min – minimum value of all utilities

  • ufun_max – maximum value of all utilities

  • scale – Scales the ufun values. Can be a callable or ‘log’, ‘exp’, ‘linear’. If None, it is ‘linear’

is_better(first: Outcome | None, second: Outcome | None, epsilon: float = 1e-10) → bool | None[source]

Compares two offers using the ufun returning whether the first is better than the second.

Parameters:

  • first – First outcome to be compared

  • second – Second outcome to be compared

  • epsilon – comparison threshold. If the utility difference within the range [-epsilon, epsilon] the two outcomes are assumed to be compatible

Returns:

True if utility(first) > utility(second) + epsilon, None if the absolute difference is <= epsilon or the ufun is not defined, False if utility(first) < utility(second) - epsilon.

property thresholds: list[float] | None[source]

Returns the internal thresholds and None if they do not exist

class negmas.negotiators.Negotiator(name: str | None = None, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, parent: Controller | None = None, owner: Agent | None = None, id: str | None = None, type_name: str | None = None, private_info: dict[str, Any] | None = None)[source]

Bases: Rational, Notifiable, Generic[TNMI, TState]

Abstract negotiation agent. Base class for all negotiators

Parameters:

  • name – Negotiator name. If not given it is assigned by the system (unique 16 characters).

  • preferences – The preferences of the agent (pass either this or ufun)

  • ufun – The ufun of the agent (overrides preferences if given)

  • parent – The Controller that controls this neogtiator (if any)

  • owner – The Agent that own this negotiator (if any)

  • id – The unique ID of the negotiator

  • private_info –

    Arbitrary information passed to the negotiator. As a special case if a value for ‘opponent_ufun’ is given, it will be accessible as self.opponent_ufun

    Returns:

    bool: True if participating in the given negotiation (or any negotiation if it was None)

    Remarks:

add_capabilities(capabilities: dict) → None[source]

Adds named capabilities to the negotiator.

Parameters:

capabilities – The capabilities to be added as a dict

Returns:

None

Remarks:

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

property ami: TNMI[source]

Agent-Mechanism Interface (deprecated, use nmi instead).

Returns:

The negotiation mechanism interface for this negotiator

Return type:

TNMI

property annotation: dict[str, Any][source]

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

before_death(cntxt: dict[str, Any]) → bool[source]

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

cancel(reason=None) → None[source]

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.

property capabilities: dict[str, Any][source]

Agent capabilities

is_acceptable_as_agreement(outcome: Outcome) → bool[source]

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.

isin(negotiation_id: str | None) → bool[source]

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: TNMI, state: TState, *, preferences: Preferences | None = None, ufun: BaseUtilityFunction | None = None, role: str = 'negotiator') → bool[source]

Called by the mechanism when the agent is about to enter a negotiation. It can prevent the agent from entering

Parameters:

  • nmi – The negotiation.

  • state – The current state of the negotiation

  • preferences – The preferences used by the negotiator (see ufun )

  • ufun – The ufun function to use (overrides negmas.preferences )

  • role – role of the negotiator.

Returns:

bool indicating whether or not the agent accepts to enter. If False is returned it will not enter the negotiation

Remarks:

  • Joining a neogiation will fail in the following conditions:

    1. The negotiator already has preferences and is asked to join with new ones

    2. The negotiator is already in a negotiation

property nmi: TNMI[source]

Negotiator-Mechanism Interface providing access to negotiation state and actions.

Returns:

Interface for interacting with the negotiation mechanism

Return type:

TNMI

on_leave(state: TState) → None[source]

A call back called after leaving a negotiation.

Parameters:

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

on_mechanism_error(state: TState) → None[source]

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

Parameters:

state – MechanismState giving current state of the negotiation.

Remarks:

  • The default behavior is to do nothing.

  • Override this to hook some action

on_negotiation_end(state: TState) → None[source]

A call back called at each negotiation end

Parameters:

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

Remarks:
on_negotiation_start(state: TState) → None[source]

A call back called at each negotiation start

Parameters:

state – MechanismState giving current state of the negotiation.

Remarks:

  • You MUST call the super() version of this function either before or after your code when you are overriding it.

  • on_negotiation_start and on_negotiation_end will always be called once for every agent.

on_notification(notification: Notification, notifier: str)[source]

Called whenever the agent receives a notification

Parameters:

  • notification – The notification object containing type and data payload.

  • notifier – The ID of the mechanism or entity that sent the notification.

Returns:

None

Remarks:

  • You MUST call the super() version of this function either before or after your code when you are overriding it.

on_round_end(state: TState) → None[source]

A call back called at each negotiation round end

Parameters:

state – MechanismState giving current state of the negotiation.

Remarks:

  • The default behavior is to do nothing.

  • Override this to hook some action

on_round_start(state: TState) → None[source]

A call back called at each negotiation round start

Parameters:

state – MechanismState giving current state of the negotiation.

Remarks:

  • The default behavior is to do nothing.

  • Override this to hook some action.

property opponent_ufun: BaseUtilityFunction | None[source]

Opponent’s utility function if known from private information.

Returns:

Opponent’s utility function or None if unknown

Return type:

BaseUtilityFunction | None

property owner: Agent | None[source]

Returns the owner agent of the negotiator

property parent: Controller | None[source]

Returns the parent controller

property private_info: dict[str, Any][source]

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

remove_capability(name: str) → None[source]

Removes named capability from the negotiator

Parameters:

capabilities – The capabilities to be added as a dict

Returns:

None

Remarks:

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

set_preferences(value: Preferences | None, force=False, ignore_exceptions: bool = False) → Preferences | None[source]

Set the negotiator’s preferences, with optional constraint handling.

Parameters:

  • value – The new preferences to assign to this negotiator.

  • force – If True, bypass validation and set preferences unconditionally.

  • ignore_exceptions – If True, suppress any exceptions during assignment.

Returns:

The previously held preferences, if any.

Return type:

Preferences | None

class negmas.negotiators.NegotiatorInfo(negotiator, context)[source]

Bases: tuple

context[source]

Alias for field number 1

negotiator[source]

Alias for field number 0

class negmas.negotiators.PolyAspiration(max_aspiration: float, aspiration_type: Literal['boulware'] | Literal['conceder'] | Literal['linear'] | Literal['hardheaded'] | float)[source]

Bases: Aspiration

A polynomially conceding curve

Parameters:

  • max_aspiration – The aspiration level to start from (usually 1.0)

  • aspiration_type – The aspiration type. Can be a string (“boulware”, “linear”, “conceder”) or a number giving the exponent of the aspiration curve.

utility_at(t: float) → float[source]

The aspiration level

Parameters:

t – relative time (a number between zero and one)

Returns:

aspiration level

class negmas.negotiators.RankerNegotiator(*args, **kwargs)[source]

Bases: Negotiator

A negotiator that can be asked to rank outcomes. By default is just consults the ufun.

To change that behavior, override rank.

It has the rank capability.

is_better(first: Outcome | None, second: Outcome | None, epsilon: float = 1e-10) → bool | None[source]

Compares two offers using the ufun returning whether the first is better than the second.

Parameters:

  • first – First outcome to be compared

  • second – Second outcome to be compared

  • epsilon – comparison threshold. If the utility difference within the range [-epsilon, epsilon] the two outcomes are assumed to be compatible

Returns:

True if utility(first) > utility(second) + epsilon, None if the absolute difference is <= epsilon or the ufun is not defined, False if utility(first) < utility(second) - epsilon.

rank(outcomes: list[Outcome | None], descending=True) → list[int][source]

Ranks the given list of outcomes. None stands for the null outcome.

Returns:

  • A list of integers in the specified order of utility values of outcomes

class negmas.negotiators.RankerWithWeightsNegotiator(*args, **kwargs)[source]

Bases: Negotiator

A negotiator that can be asked to rank outcomes returning rank and weight. By default is just consults the ufun.

To change that behavior, override rank_with_weights.

It has the rank-weighted capability.

is_better(first: Outcome | None, second: Outcome | None, epsilon: float = 1e-10) → bool | None[source]

Compares two offers using the ufun returning whether the first is better than the second.

Parameters:

  • first – First outcome to be compared

  • second – Second outcome to be compared

  • epsilon – comparison threshold. If the utility difference within the range [-epsilon, epsilon] the two outcomes are assumed to be compatible

Returns:

True if utility(first) > utility(second) + epsilon, None if the absolute difference is <= epsilon or the ufun is not defined, False if utility(first) < utility(second) - epsilon.

rank_with_weights(outcomes: list[Outcome] | None, descending=True) → list[tuple[int, float]][source]

Ranks the given list of outcomes with weights. None stands for the null outcome. Outcomes of equal utility are ordered arbitrarily.

Returns:

  • an integer giving the index in the input array (outcomes) of an outcome

    • the weight of that outcome

  • The list is sorted by weights descendingly

Return type:

  • A list of tuples each with two values

class negmas.negotiators.RealComparatorNegotiator(*args, **kwargs)[source]

Bases: Negotiator

A negotiator that can be asked to evaluate outcomes using its internal ufun.

Th change the way it evaluates outcomes, override compare_real

It has the compare-real capability

difference(first: Outcome, second: Outcome) → float[source]

Compares two offers using the ufun returning the difference in their utility

Parameters:

  • first – First outcome to be compared

  • second – Second outcome to be compared

Returns:

An estimate of the differences between the two outcomes. It can be a real number between -1, 1 or a probability distribution over the same range.

Return type:

“Value”

is_better(first: Outcome | None, second: Outcome | None) → bool | None[source]

Compares two offers using the ufun returning whether the first is better than the second.

Parameters:

  • first – First outcome to be compared

  • second – Second outcome to be compared

Returns:

True if utility(first) > utility(second) + epsilon, None if the absolute difference is <= epsilon or the ufun is not defined, False if utility(first) < utility(second) - epsilon.

class negmas.negotiators.SorterNegotiator(*args, **kwargs)[source]

Bases: Negotiator

A negotiator that can be asked to rank outcomes returning rank without weight. By default is just consults the ufun.

To change that behavior, override sort.

It has the sort capability.

sort(outcomes: list[Outcome | None], descending=True) → None[source]

Ranks the given list of outcomes. None stands for the null outcome.

Returns:

  • The outcomes are sorted IN PLACE.

  • There is no way to know if the ufun is not defined from the return value. Use has_preferences to check for the availability of the ufun

class negmas.negotiators.TimeCurve(*args, **kwargs)[source]

Bases: Protocol

Models a time-curve mapping relative timge (going from 0.0 to 1.0) to a utility range to use

abstractmethod utility_range(t: float) → tuple[float, float][source]

Utility range.

Parameters:

t –

Returns:

The result.

Return type:

tuple[float, float]