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

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]¶: Completed.

property done[source]¶: Done.

property ended[source]¶: Ended.

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]¶: Keys.

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]¶: Values.

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, time_limit: float, pend: float, pend_per_second: float, step_time_limit: float, negotiator_time_limit: float, n_steps: int | None, dynamic_entry: bool, max_n_negotiators: int | None, _mechanism: Mechanism, annotation: dict[str, Any]=<class 'dict'>)[source]¶

Bases: object

All information of a negotiation visible to negotiators.

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

property agent_names: list[str][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]¶

Atomic steps.

Returns:: The result.
Return type:: bool

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]¶

History.

Returns:: The result.
Return type:: list

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

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

Issues.

Returns:: The result.
Return type:: tuple[Issue, …]

keys()[source]¶: Keys.

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 allowed number of steps for this negotiation. None indicates infinity

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]¶

Participants.

Returns:: The result.
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

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

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 time limit in seconds for this negotiation session. None indicates infinity

values()[source]¶: Values.

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.

General = 1[source]¶

OSExpanded = 9[source]¶

OSRestricted = 8[source]¶

ReservedOutcome = 5[source]¶

ReservedValue = 4[source]¶

Scale = 2[source]¶

Shift = 3[source]¶

UncertaintyIncreased = 7[source]¶

UncertaintyReduced = 6[source]¶

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

Bases: tuple

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

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

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