negmas.common¶

Common data-structures and classes used by all other modules.

This module does not import anything from the library except during type checking

negmas.common.AgentMechanismInterface[source]¶: A depricated alias for NegotiatorMechanismInterface

negmas.common.DEFAULT_JAVA_PORT = 25337[source]¶: Default port to use for connecting to GENIUS

negmas.common.DEFAULT_RESERVED_VALUE_PENALTY = 0.0[source]¶: Default penalty applied when correcting non-finite reserved values (None, inf, -inf, NaN). The corrected value is set to ufun.min() - DEFAULT_RESERVED_VALUE_PENALTY.

class negmas.common.MechanismAction[source]¶

Bases: object

Defines a negotiation action

class negmas.common.MechanismState(running: bool = False, waiting: bool = False, started: bool = False, step: int = 0, time: float = 0.0, relative_time: float = 0.0, broken: bool = False, timedout: bool = False, agreement: tuple | None = None, results: tuple | OutcomeSpace | tuple[tuple] | None = None, n_negotiators: int = 0, has_error: bool = False, error_details: str = '', erred_negotiator: str = '', erred_agent: str = '')[source]¶

Bases: object

Encapsulates the mechanism state at any point

agreement: tuple | None[source]¶: Agreement at the end of the negotiation (it is always None until an agreement is reached).

asdict()[source]¶: Converts the outcome to a dict containing all fields

broken: bool[source]¶: True if the negotiation has started and ended with an END_NEGOTIATION

property completed[source]¶: Alias for ended. Whether the negotiation has concluded.

property done[source]¶: Alias for ended. Whether the negotiation has concluded.

property ended[source]¶: Whether the negotiation has concluded, regardless of outcome.

erred_agent: str[source]¶: ID of the agent owning the negotiator that raised the last error

erred_negotiator: str[source]¶: ID of the negotiator that raised the last error

error_details: str[source]¶: Details of the error if any

has_error: bool[source]¶: Does the mechanism have any errors

keys()[source]¶: Returns the field names of the mechanism state.

n_negotiators: int[source]¶: Number of agents currently in the negotiation. Notice that this may change over time if the mechanism supports dynamic entry

relative_time: float[source]¶: A number in the period [0, 1] giving the relative time of the negotiation. Relative time is calculated as max(step/n_steps, time/time_limit).

results: tuple | OutcomeSpace | tuple[tuple] | None[source]¶: In its simplest form, an agreement is a single outcome (or None for failure). Nevertheless, it can be a tuple of outcomes or even a complete outcome space.

running: bool[source]¶: Whether the negotiation has started and did not yet finish

started: bool[source]¶: Whether the negotiation has started

step: int[source]¶: The current round of the negotiation

time: float[source]¶: The current real time of the negotiation.

timedout: bool[source]¶: True if the negotiation was timedout

values()[source]¶: Returns the field values of the mechanism state.

waiting: bool[source]¶: Whether the negotiation is waiting for some negotiator to respond

class negmas.common.NegotiatorInfo(name: str, id: str, type: str)[source]¶

Bases: object

Keeps information about a negotiator. Mostly for use with controllers.

id: str[source]¶: ID unique to this negotiator

name: str[source]¶: Name of this negotiator

type: str[source]¶: Type of the negotiator as a string

class negmas.common.NegotiatorMechanismInterface(id: str, n_outcomes: int | float, outcome_space: OutcomeSpace, shared_time_limit: float, shared_n_steps: int | None, private_time_limit: float, private_n_steps: int | None, pend: float, pend_per_second: float, step_time_limit: float, negotiator_time_limit: float, dynamic_entry: bool, max_n_negotiators: int | None, _mechanism: Mechanism, annotation: dict[str, Any] = NOTHING)[source]¶

Bases: object

All information of a negotiation visible to negotiators.

The NMI provides negotiators with access to mechanism parameters and state. It supports per-negotiator time and step limits through a three-tier system:

Shared limits (shared_time_limit, shared_n_steps): Apply to all negotiators
Private limits (private_time_limit, private_n_steps): Apply to individual negotiators
Effective limits (time_limit, n_steps): Computed as min(shared, private)

The effective limits are what negotiators actually see and are used to calculate relative_time. This design allows different negotiators to have different time/step constraints while maintaining backward compatibility with code that doesn’t use per-negotiator limits.

Examples

Standard usage (all negotiators see same limits):

mechanism = SAOMechanism(time_limit=60, n_steps=100)
# All negotiators see time_limit=60, n_steps=100

Per-negotiator limits:

mechanism = SAOMechanism(time_limit=60, n_steps=100)
mechanism.add(negotiator1, time_limit=30)  # Sees time_limit=30 (stricter)
mechanism.add(
    negotiator2, time_limit=90
)  # Sees time_limit=60 (shared is stricter)
mechanism.add(negotiator3)  # Sees time_limit=60 (no private limit)

property agent_ids: list[str | None][source]¶: Gets the IDs of all agents owning all negotiators

property agent_names: list[str | None][source]¶: Gets the names of all agents owning all negotiators

annotation: dict[str, Any][source]¶: An arbitrary annotation as a dict[str, Any] that is always available for all negotiators

asdict()[source]¶: Converts the object to a dict containing all fields

property atomic_steps: bool[source]¶: Whether steps in this mechanism are atomic (cannot be interrupted).

property cartesian_outcome_space: CartesianOutcomeSpace[source]¶

Returns the outcome_space as a CartesianOutcomeSpace or raises a ValueError if that was not possible.

Remarks:

Useful for negotiators that only work with CartesianOutcomeSpace s (i.e. GeniusNegotiator )

discrete_outcome_space(levels: int = 5, max_cardinality: int = 10000000000) → DiscreteOutcomeSpace[source]¶: Returns a stable discrete version of the given outcome-space

discrete_outcomes(max_cardinality: int | float = inf) → Iterable[tuple][source]¶

A discrete set of outcomes that spans the outcome space

Parameters:: max_cardinality – The maximum number of outcomes to return. If None, all outcomes will be returned for discrete outcome-spaces
Returns:: list of n or less outcomes
Return type:: list[Outcome]

dynamic_entry: bool[source]¶: Whether it is allowed for negotiators to enter/leave the negotiation after it starts

property estimated_n_steps: int[source]¶: Return an estimate of the number of steps for this negotiation.

property estimated_time_limit: float[source]¶: Return an estimate of the number of seconds for this negotiation.

genius_id(id: str | None) → str | None[source]¶: Gets the Genius ID corresponding to the given negotiator if known otherwise its normal ID

property genius_negotiator_ids: list[str][source]¶: Gets the Java IDs of all negotiators (if the negotiator is not a GeniusNegotiator, its normal ID is returned)

property history: list[source]¶

The full negotiation history of actions, offers, and responses.

Returns:: Chronological list of all negotiation events and actions
Return type:: list

id: str[source]¶: Mechanism session ID. That is unique for all mechanisms

property issues: tuple[Issue, ...][source]¶

The negotiation issues defining the outcome space dimensions.

Returns:: Tuple of Issue objects (e.g., price, quantity, delivery time)
Return type:: tuple[Issue, …]

keys()[source]¶: Returns the field names of the NMI.

log_critical(nid: str, data: dict[str, Any]) → None[source]¶: Logs at critical level

log_debug(nid: str, data: dict[str, Any]) → None[source]¶: Logs at debug level

log_error(nid: str, data: dict[str, Any]) → None[source]¶: Logs at error level

log_info(nid: str, data: dict[str, Any]) → None[source]¶: Logs at info level

log_warning(nid: str, data: dict[str, Any]) → None[source]¶: Logs at warning level

max_n_negotiators: int | None[source]¶: Maximum allowed number of negotiators in the session. None indicates no limit

property mechanism_id: str[source]¶: Gets the ID of the mechanism

property n_negotiators: int[source]¶: Syntactic sugar for state.n_negotiators

n_outcomes: int | float[source]¶: Number of outcomes which may be float('inf') indicating infinity

n_steps: int | None[source]¶: The effective allowed number of steps for this negotiator. Computed as min(shared_n_steps, private_n_steps) in __attrs_post_init__

property negotiator_ids: list[str][source]¶: Gets the IDs of all negotiators

negotiator_index(source: str) → int[source]¶: Returns the negotiator index for the given negotiator. Raises an exception if not found

negotiator_time_limit: float[source]¶: The time limit in seconds to wait for negotiator responses of this negotiation session. None indicates infinity

outcome_space: OutcomeSpace[source]¶: Negotiation agenda as as an OutcomeSpace object. The most common type is CartesianOutcomeSpace which represents the cartesian product of a list of issues

property outcomes: Iterable[tuple] | None[source]¶: All outcomes for discrete outcome spaces or None for continuous outcome spaces. See discrete_outcomes

property params[source]¶: Returns the parameters used to initialize the mechanism.

property participants: list[NegotiatorInfo][source]¶

Information about all negotiators participating in this negotiation.

Returns:: List of participant information including IDs and preferences
Return type:: list[NegotiatorInfo]

pend: float[source]¶: The probability that the negotiation times out at every step. Must be less than one. If <= 0, it is ignored

pend_per_second: float[source]¶: The probability that the negotiation times out every second. Must be less than one. If <= 0, it is ignored

private_n_steps: int | None[source]¶: The private allowed number of steps for this negotiator. None indicates infinity. Set via Mechanism.add(n_steps=…)

private_time_limit: float[source]¶: The private time limit in seconds for this negotiator. inf indicates infinity. Set via Mechanism.add(time_limit=…)

random_outcome() → tuple[source]¶: A single random outcome.

random_outcomes(n: int = 1) → list[tuple][source]¶

A set of random outcomes from the outcome-space of this negotiation

Parameters:: n – number of outcomes requested
Returns:: list of n or less outcomes
Return type:: list[Outcome]

property requirements: dict[source]¶

The protocol requirements

Returns:

A dict of str/Any pairs giving the requirements

shared_n_steps: int | None[source]¶: The shared allowed number of steps for this negotiation. Applies to all negotiators. None indicates infinity

shared_time_limit: float[source]¶: The shared time limit in seconds for this negotiation session. Applies to all negotiators. inf indicates infinity

property state: MechanismState[source]¶

Access the current state of the mechanism.

Remarks:

Whenever a method receives a AgentMechanismInterface object, it can always access the current state of the protocol by accessing this property.

step_time_limit: float[source]¶: The time limit in seconds for each step of this negotiation session. None indicates infinity

time_limit: float[source]¶: The effective time limit in seconds for this negotiator. Computed as min(shared_time_limit, private_time_limit) in __attrs_post_init__

values()[source]¶: Returns the field values of the NMI.

class negmas.common.PreferencesChange(type: PreferencesChangeType = PreferencesChangeType.General, data: Any = None)[source]¶

Bases: object

PreferencesChange implementation.

data: Any[source]¶

type: PreferencesChangeType[source]¶

class negmas.common.PreferencesChangeType(*values)[source]¶

Bases: Enum

The type of change in preferences.

Remarks:

Returned from changes property of Preferences to help the owner of the preferences in deciding what to do with the change.

Received by the on_preferences_changed method of Rational entities to inform them about a change in preferences.

Note that the Rational entity needs to call changes explicitly and call its own on_preferences_changed to handle changes that happen without assignment to negmas.preferences of the Rational entity.

If the negmas.preferences of the Rational agent are changed through assignment, its on_preferences_changed will be called with the appropriate PreferencesChange list.

Dissociated = 14[source]¶

General = 1[source]¶

Initialization = 13[source]¶

OSExpanded = 9[source]¶

OSRestricted = 8[source]¶

ReservedOutcome = 5[source]¶

ReservedValue = 4[source]¶

Scale = 2[source]¶

Shift = 3[source]¶

StabilityChanged = 12[source]¶

StabilityIncreased = 11[source]¶

StabilityReduced = 10[source]¶

UncertaintyIncreased = 7[source]¶

UncertaintyReduced = 6[source]¶

class negmas.common.TraceElement(time, relative_time, step, negotiator, offer, responses, state, text, data)[source]¶

Bases: tuple

An element of the trace returned by full_trace representing the history of the negotiation

data[source]¶: Alias for field number 8

negotiator[source]¶: Alias for field number 3

offer[source]¶: Alias for field number 4

relative_time[source]¶: Alias for field number 1

responses[source]¶: Alias for field number 5

state[source]¶: Alias for field number 6

step[source]¶: Alias for field number 2

text[source]¶: Alias for field number 7

time[source]¶: Alias for field number 0

negmas.common.Value[source]¶

A value in NegMAS can either be crisp ( float ) or probabilistic ( Distribution )

alias of Distribution | float