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.

before_death(cntxt: dict) → bool[source]¶

Called whenever the parent negotiator is about to be killed by its controller.

Parameters:: cntxt – Context information about the death.
Returns:: True if the component agrees to the negotiator being killed, False otherwise. Note that the controller can still force-kill the negotiator.

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.

cancel(reason=None) → None[source]¶

Called when the mechanism requests the negotiator to cancel its current processing.

Parameters:: reason – Optional reason for the cancellation.

Remarks:

Components can use this to interrupt long-running computations.
The default implementation does nothing.

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.

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 .

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.MetaNegotiator(*args, negotiators: Iterable[Negotiator] | None = None, negotiator_types: Iterable[type[Negotiator]] | None = None, negotiator_params: Iterable[dict[str, Any]] | None = None, negotiator_names: Iterable[str] | None = None, share_ufun: bool = True, share_nmi: bool = True, **kwargs)[source]¶

Bases: Negotiator

A meta-negotiator that contains and delegates to multiple full Negotiator objects.

Unlike ModularNegotiator which uses Component objects (behavior pieces), MetaNegotiator works with complete Negotiator instances, allowing for ensemble or delegation-based negotiation strategies.

The meta-negotiator delegates all lifecycle callbacks to its sub-negotiators. Subclasses must implement aggregation strategies for actions like propose and respond (in protocol-specific subclasses like GBMetaNegotiator).

Parameters:

negotiators – An iterable of Negotiator instances to manage. Mutually exclusive with negotiator_types.
negotiator_types – An iterable of Negotiator types to instantiate. Mutually exclusive with negmas.negotiators.
negotiator_params – Optional iterable of parameter dicts for each negotiator type. Only used with negotiator_types.
negotiator_names – Optional names for the negotiators.
share_ufun – If True (default), sub-negotiators will share the parent’s ufun.
share_nmi – If True (default), sub-negotiators will receive the parent’s NMI on join.
*args – Additional positional arguments passed to the base class.
**kwargs – Additional keyword arguments passed to the base class.

Remarks:

Sub-negotiators share the parent’s NMI and ufun when share_nmi and share_ufun are True (the defaults).
All lifecycle callbacks are delegated to all sub-negotiators.
Protocol-specific subclasses (e.g., GBMetaNegotiator) must implement aggregation strategies for propose and respond.
You can either pass negmas.negotiators (instances) OR negotiator_types (classes to instantiate). If using negotiator_types, you can optionally provide negotiator_params (parameter dicts).

Examples

Create a meta-negotiator from existing negotiator instances:

>>> from negmas.sao.negotiators import BoulwareTBNegotiator, ConcederTBNegotiator
>>> from negmas.sao.negotiators import MeanMetaNegotiator
>>> meta = MeanMetaNegotiator(
...     negotiators=[BoulwareTBNegotiator(), ConcederTBNegotiator()]
... )

Create a meta-negotiator from negotiator types:

>>> meta = MeanMetaNegotiator(
...     negotiator_types=[BoulwareTBNegotiator, ConcederTBNegotiator]
... )

Create a meta-negotiator from types with parameters:

>>> meta = MeanMetaNegotiator(
...     negotiator_types=[BoulwareTBNegotiator, ConcederTBNegotiator],
...     negotiator_params=[{"name": "boulware"}, {"name": "conceder"}]
... )

add_negotiator(negotiator: Negotiator, name: str | None = None, index: int = -1) → None[source]¶

Add a sub-negotiator at the given index.

Parameters:

negotiator – The negotiator to add.
name – Optional name for the negotiator.
index – Position to insert at. If negative, appends at the end.

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

Ask all sub-negotiators if they accept death.

Returns False if any sub-negotiator returns False, but the controller can still force-kill the meta-negotiator.

Parameters:: cntxt – Context information about the death.
Returns:: True if all sub-negotiators agree to death, False otherwise.

cancel(reason=None) → None[source]¶

Cancel processing in all sub-negotiators.

Parameters:: reason – Optional reason for the cancellation.

get_negotiator(name: str) → Negotiator | None[source]¶

Get a sub-negotiator by name.

Parameters:: name – The name of the negotiator.
Returns:: The negotiator, or None if not found.

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

Join a negotiation and optionally have sub-negotiators join too.

When share_nmi is True, sub-negotiators will also join the negotiation with the same NMI. When share_ufun is True, they will use the parent’s ufun.

Parameters:

nmi – The negotiator-mechanism interface.
state – The current mechanism state.
preferences – Optional preferences for this negotiator.
ufun – Optional utility function (overrides preferences).
role – The role in the negotiation.

Returns:

True if successfully joined, False otherwise.

property negotiator_names: tuple[str, ...][source]¶

Return the names of all sub-negotiators.

Returns:: A tuple of negotiator names.

property negotiators: tuple[Negotiator, ...][source]¶

Return the tuple of sub-negotiators.

Returns:: A tuple of all sub-negotiators.

on_leave(state: MechanismState) → None[source]¶

Notify all sub-negotiators that we’re leaving the negotiation.

Parameters:: state – The current mechanism state.

on_mechanism_error(state: MechanismState) → None[source]¶

Notify all sub-negotiators of a mechanism error.

Parameters:: state – The current mechanism state.

on_negotiation_end(state: MechanismState) → None[source]¶

Notify all sub-negotiators that negotiation has ended.

Parameters:: state – The current mechanism state.

on_negotiation_start(state: MechanismState) → None[source]¶

Notify all sub-negotiators that negotiation has started.

Parameters:: state – The current mechanism state.

on_preferences_changed(changes: list[PreferencesChange]) → None[source]¶

Notify all sub-negotiators of preference changes.

Parameters:: changes – The list of preference changes.

on_round_end(state: MechanismState) → None[source]¶

Notify all sub-negotiators that a round has ended.

Parameters:: state – The current mechanism state.

on_round_start(state: MechanismState) → None[source]¶

Notify all sub-negotiators that a round has started.

Parameters:: state – The current mechanism state.

remove_negotiator(name: str) → Negotiator | None[source]¶

Remove and return the negotiator with the given name.

Parameters:: name – The name of the negotiator to remove.
Returns:: The removed negotiator, or None if not found.

remove_negotiator_at(index: int) → Negotiator | None[source]¶

Remove and return the negotiator at the given index.

Parameters:: index – The index of the negotiator to remove.
Returns:: The removed negotiator, or None if index is out of bounds.

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.

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

Called whenever the parent is about to kill this negotiator.

Delegates to all components. Returns False if any component returns False, but the controller can still force-kill the negotiator.

Parameters:: cntxt – Context information about the death.
Returns:: True if all components agree to the death, False otherwise.
Return type:: bool

cancel(reason=None) → None[source]¶

Called by the mechanism to make the negotiator cancel its current processing.

Delegates to all components so they can interrupt their processing.

Parameters:: reason – Optional reason for the cancellation.

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.

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

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 negotiator (if any)
owner – The Agent that owns 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

Callback Lifecycle:

When a negotiator participates in a negotiation, callbacks are invoked in this guaranteed order:

Joining Phase (mechanism.add() or negotiator.join()): - join(nmi, state, preferences, role) - can reject by returning False
Negotiation Start (first mechanism.step() or mechanism.run()): - [owner set on preferences] - on_preferences_changed([Initialization]) - ALWAYS FIRST (if preferences exist) - on_negotiation_start(state) - ALWAYS SECOND - on_round_start(state) - first round begins
Negotiation Rounds (repeated): - propose(state) - make an offer - respond(state, offer, source) - evaluate an offer - on_partner_proposal(...) / on_partner_response(...) - on_round_end(state) / on_round_start(state)
Negotiation End: - on_negotiation_end(state) - on_leave(state) - [owner cleared from preferences]

Key Guarantees: - on_preferences_changed([Initialization]) is ALWAYS called before on_negotiation_start() - Both are called exactly ONCE per negotiation - This order is consistent regardless of when preferences were set (constructor or join) - See Available Negotiators for the full callback flowchart

Remarks:

ufun overrides negmas.preferences. You need to pass only one of them

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:

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

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:

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: 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_negotiator_didnot_enter(negotiator_id: str, state: TState) → None[source]¶

A callback called when a negotiator tried but failed to enter the negotiation.

Parameters:

negotiator_id – The ID of the negotiator that failed to enter.
state – MechanismState giving current state of the negotiation.

Remarks:

The default behavior is to do nothing.
Override this to hook some action when a partner fails to join.

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

A callback called when a new negotiator enters the negotiation.

Parameters:

negotiator_id – The ID of the negotiator that entered.
state – MechanismState giving current state of the negotiation.

Remarks:

The default behavior is to do nothing.
Override this to hook some action when a new partner joins.

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

A callback called when another negotiator leaves the negotiation.

Parameters:

negotiator_id – The ID of the negotiator that left.
state – MechanismState giving current state of the negotiation.

Remarks:

The default behavior is to do nothing.
Override this to hook some action when a partner leaves.

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 deferred Initialization for deterministic ordering.

Parameters:

value – The new preferences to assign to this negotiator.
force – If True, call on_preferences_changed even if value equals current preferences.
ignore_exceptions – If True, suppress any exceptions during callback.

Returns:

The preferences that were set.

Return type:

Preferences | None

Remarks:

Before joining a negotiation (nmi is None): Preferences are stored but on_preferences_changed([Initialization]) is NOT called. The Initialization callback is deferred to _on_negotiation_start to ensure deterministic ordering (always after join, before on_negotiation_start).
After joining but before start: Same as above - Initialization deferred.
After negotiation started: If this is the first time setting preferences, on_preferences_changed([Initialization]) is called immediately (we missed _on_negotiation_start). If replacing existing preferences, uses General.
This ensures on_preferences_changed([Initialization]) is called exactly once per negotiation, regardless of when preferences were set.

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]