NegMAS

https://github.com/yasserfarouk/negmas
Admin
Negotiation Multi-Agent System (A negotiation library designed for situated negotiations within...
Tokens:39,999
Snippets:281
Trust Score:7.9
License:AGPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Negmas from Source

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Installs the negmas library from the downloaded or cloned source code using the setup.py script. This command should be run from the root directory of the negmas source code.

```shell
$ python setup.py install
```

--------------------------------

### Install Negmas Latest Commit from GitHub

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Installs the negmas library directly from the latest commit on the master branch of the GitHub repository using pip. Note that this version may not be stable.

```shell
$ pip install git+https://github.com/yasserfarouk/negmas
```

--------------------------------

### Clone Negmas GitHub Repository

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Clones the public negmas repository from GitHub to your local machine using the git command-line tool. This is the first step if you intend to install from source.

```shell
$ git clone git://github.com/yasserfarouk/negmas
```

--------------------------------

### Download and Unzip Example Scenario (Windows PowerShell)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Downloads an example negotiation scenario ZIP file using Invoke-WebRequest, unzips its contents into a specified directory within the user's home directory using the 7z command (requires 7-Zip installed), and then removes the downloaded ZIP file. This prepares a sample scenario for use in negotiations on Windows.

```powershell
Invoke-WebRequest -Uri https://yasserfarouk.github.io/files/CameraB.zip -OutFile $HOME/negmas/scenarios/CameraB.zip
7z x $HOME/negmas/scenarios/CameraB.zip -o$HOME\negmas\scenarios
Remove-Item $HOME/negmas/scenarios/CameraB.zip
```

--------------------------------

### Install Negmas Stable Release

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Installs the latest stable release of the negmas library from the Python Package Index (PyPI) using pip. This is the standard and recommended method for installation.

```shell
$ pip install negmas
```

--------------------------------

### Install NegMAS Genius Bridge (bash)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Runs the NegMAS setup command to download and prepare the Genius bridge JAR file and necessary configurations after NegMAS is installed. This is the recommended method for setting up the bridge.

```bash
negmas genius-setup
```

--------------------------------

### Configuring Buyer with Boulware Concession

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Starts the configuration of a negotiation session, specifically adding a buyer agent configured to use the 'boulware' concession curve.

```python
session = SAOMechanism(issues=issues, n_steps=5000)
session.add(
    TimeBasedConcedingNegotiator(name="buyer", offering_curve="boulware"),
    ufun=buyer_utility,
)
session.add(
```

--------------------------------

### Download and Unzip Example Scenario (Linux/macOS bash)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Downloads an example negotiation scenario ZIP file using curl, unzips its contents into a specified directory within the user's home directory, and then removes the downloaded ZIP file. This prepares a sample scenario for use in negotiations.

```bash
curl https://yasserfarouk.github.io/files/CameraB.zip --create-dirs -o $HOME/negmas/scenarios/CameraB.zip
unzip $HOME/negmas/scenarios/CameraB.zip -d $HOME/negmas/scenarios/
rm $HOME/negmas/scenarios/CameraB.zip
```

--------------------------------

### Download Negmas Tarball from GitHub

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Downloads the source code of the negmas library as a tarball archive from the master branch of the GitHub repository using the curl command. This is an alternative to cloning if you want the source code.

```shell
$ curl  -OL https://github.com/yasserfarouk/negmas/tarball/master
```

--------------------------------

### Getting Help for NegMAS Genius CLI (Console)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/scripts.rst

Displays the help message and lists the available options and arguments for the `negmas genius` command. This command is used to start the Genius Bridge JVM.

```console
$ negmas genius --help
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Creates a directory named 'workspace', changes into it, creates a virtual environment named 'venv' inside 'workspace' using the standard 'venv' module, and then activates the created virtual environment.

```shell
$ mkdir workspace; cd workspace
$ python -m venv venv
$ source venv/bin/activate
```

--------------------------------

### Configuring Allowed Negotiation Mechanisms (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

This Python dictionary example shows how to configure the `mechanisms` parameter when initializing a `World` instance. It specifies which negotiation mechanism types are allowed in the world and provides default keyword arguments for each type. In this example, it allows the SAOMechanism and STVetoMechanism with specific settings.

```python
super().__init__(mechanisms={
    "negmas.sao.SAOMechanism": dict(offering_is_accepting=False),
    "negmas.st.STVetoMechanism": dict()
},
                     ...)
```

--------------------------------

### Setting Up Virtual Environment with Poetry

Source: https://github.com/yasserfarouk/negmas/blob/master/CONTRIBUTING.rst

These commands create a Python virtual environment, activate it, and install the project in editable mode along with its development dependencies using pip.

```Shell
python -m venv .venv
source .venv/bin/activate
pip install -e .
pip install -e ".[dev]"
```

--------------------------------

### Check Python Path (*nix/macOS)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Uses the 'which' command to display the full path to the 'python' executable on *nix or macOS systems. This helps verify that the correct Python interpreter (e.g., from the virtual environment) is being used.

```shell
$ which python
```

--------------------------------

### Check Python Path (Windows)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Uses the 'where' command to display the full path to the 'python' executable on Windows systems. This helps verify that the correct Python interpreter (e.g., from the virtual environment) is being used.

```shell
$ where python
```

--------------------------------

### Example Negotiation Data Structure - Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/getting_started.rst

This snippet shows an example data structure representing negotiation offers or outcomes, likely used within the Negmas framework. It appears to be a list of tuples, where each tuple contains information about an offer, potentially including step number, agent ID, and utility.

```Python
(12, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (42,)),
(12, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (30,)),
(13, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (40,)),
(13, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (32,)),
(14, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (37,)),
(14, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (35,))
]
```

--------------------------------

### Get Executable Contracts - Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Implements the `executable_contracts` callback to retrieve contracts scheduled for execution at the current simulation step from the `_contracts` mapping.

```python
    return self._contracts[self.current_step]
```

--------------------------------

### Run NegMAS Genius Bridge (Recommended bash)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Starts the NegMAS Genius bridge process using the negmas command-line interface. It is recommended to run the bridge explicitly before starting negotiations involving Genius agents, although it may start automatically if not running.

```bash
negmas genius
```

--------------------------------

### Verify NegMAS Genius Bridge Installation (bash)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Executes the downloaded Genius bridge JAR file with the --version flag to confirm that the bridge was successfully installed and is accessible at the expected location.

```bash
java -jar $HOME/negmas/files/geniusbridge.jar --version
```

--------------------------------

### Importing the negmas Library (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Imports the main negmas library package, assuming it has been installed correctly. This is the standard way to begin using the library.

```python
import negmas
```

--------------------------------

### Update Pip

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/installation.rst

Upgrades the pip package installer to the latest version using the '-U' flag. This is recommended after activating a virtual environment to ensure you have the most recent version of pip.

```shell
$ pip install -U pip
```

--------------------------------

### Getting Help for NegMAS Tournament CLI (Console)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/scripts.rst

Shows the help message and outlines the available sub-commands and options for the `negmas tournament` command. This command is used to manage and run negotiation tournaments.

```console
$ negmas tournament --help
```

--------------------------------

### Output: Categorical Issue Example 1

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Shows the string representation of a categorical issue with two possible values.

```Output
issueQKqgvpMi: ['to be', 'not to be']
```

--------------------------------

### Output: Random Valid/Invalid Values

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Shows examples of randomly generated valid and invalid values for different issue types.

```Output
[['to be', '20250315H165549399269jJTGt6qBto be20250315H165549399295XtRgNy0I'],
 [6, 10],
 [0.6118970848141451, 1.928063278403899]]
```

--------------------------------

### Defining Valid and Invalid Outcomes in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Demonstrates how to define negotiation outcomes using Python dictionaries, showing both a valid and an invalid example based on predefined issue constraints.

```ipython3
valid_outcome = {"The Problem": "to be", "number of items": 5, "cost": 0.15}
invalid_outcome = {"The Problem": "to be", "number of items": 10, "cost": 0.15}
```

--------------------------------

### Output: Categorical Issue Example 2

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Shows the string representation of another categorical issue with two possible values.

```Output
The Problem: ['to be', 'not to be']
```

--------------------------------

### Implementing a Dynamic Utility Function in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

This example illustrates a utility function whose output changes based on internal state (`mood`). It shows how to initialize state, implement a method to change state (`set_mood`), handle different states in `eval`, and manage stationary behavior.

```python
class MoodyUtilityFunction(UtilityFunction):
    def __init__(self, mood="good", stationary=False):
        super().__init__()
        self.mood = mood
        self._stationary = stationary

    def to_stationary(self):
        return MoodyUtilityFunction(mood=self.mood, stationary=True)

    def eval(self, offer):
        if self.mood not in ("good", "bad"):
            raise ValueError(f"Cannot calculate utility for {offer}")
        return float(offer[COST]) if self.mood == "good" else 0.1 * offer[COST]

    def set_mood(self, mood):
        if self._stationary:
            return
        self.mood = mood

    def xml(self):
        pass


offer = (10,)

f = MoodyUtilityFunction()
# I am in a good mode now
print(f"Utility in good mood of {offer} is {f(offer)}")
f.set_mood("bad")
print(f"Utility in bad mood of {offer} is {f(offer)}")
f.set_mood("undecided")
try:
    y = f(offer)
except ValueError as e:
    print(f"Utility in good mood of {offer} is undecidable: {e}")
```

--------------------------------

### Run Command-Line Negotiation (With Plot bash)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Executes a negotiation simulation from the command line using the negotiate command, similar to the previous example. This version enables plotting (--plot) to visualize the negotiation process, including a native NegMAS agent and a Genius agent.

```bash
negotiate $HOME/negmas/scenarios/CameraB --plot -p sao -n AspirationNegotiator -n genius.BoulwareNegotiationParty --steps=100
```

--------------------------------

### Creating AspirationNegotiator Agents in NegMAS (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Generates a list of five AspirationNegotiator agents using a list comprehension. These agents implement a simple time-based negotiation strategy, starting with their maximum utility outcome and conceding over time.

```python
negotiators = [AspirationNegotiator(name=f"a{_}") for _ in range(5)]
```

--------------------------------

### Example Negotiation Data Points - Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/getting_started.rst

This snippet shows a list of tuples, where each tuple represents a data point in a negotiation. The format is (round_number, agent_id, (value,)). This structure likely logs the state or action of agents at specific negotiation rounds.

```Python
(6, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (16,)),
(7, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (48,)),
(7, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (18,)),
(8, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (48,)),
(8, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (21,)),
(9, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (47,)),
(9, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (23,)),
(10, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (46,)),
(10, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (25,)),
(11, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (44,)),
(11, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (28,)),
```

--------------------------------

### Initializing World Constructor in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Demonstrates how to call the base `World` class constructor within the `__init__` method, forcing specific parameters like `awi_type`, `negotiation_quota_per_step`, `force_signing`, and `default_signing_delay` to configure the world's behavior.

```python
    kwargs["awi_type"] = AWI
    kwargs["negotiation_quota_per_step"] = kwargs.get(
        "negotiation_quota_per_step", 8
    )
    kwargs["force_signing"] = True
    kwargs["default_signing_delay"] = 0    
    super().__init__(*args, **kwargs)
```

--------------------------------

### Setting up Negotiation Mechanism and Issues - Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/getting_started.rst

Imports necessary classes from NegMAS and sets up the negotiation environment. It defines a single issue 'price' with 50 discrete values and initializes an SAOMechanism, which implements the Stacked Alternating Offers protocol, with the defined issue and a maximum of 20 steps.

```python
from negmas import make_issue, SAOMechanism, TimeBasedConcedingNegotiator
from negmas.sao.negotiators import BoulwareTBNegotiator as Boulware
from negmas.sao.negotiators import LinearTBNegotiator as Linear
from negmas.preferences import LinearAdditiveUtilityFunction as UFun
from negmas.preferences.value_fun import IdentityFun, AffineFun
import matplotlib.pyplot as plt


# create negotiation agenda (issues)
issues = [make_issue(name="price", values=50)]

# create the mechanism
mechanism = SAOMechanism(issues=issues, n_steps=20)
```

--------------------------------

### Setting up and Running a Simple SAO Negotiation in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

This snippet initializes a negotiation session using the SAOMechanism, defines the negotiation issues (price, quantity, delivery time), creates linear additive utility functions for a buyer and a seller based on these issues, adds time-based conceding negotiators with their respective preferences, and finally runs the negotiation session to find an agreement.

```python
from negmas import (
    make_issue,
    SAOMechanism,
    NaiveTitForTatNegotiator,
    TimeBasedConcedingNegotiator,
)
from negmas.preferences import LinearAdditiveUtilityFunction as LUFun
from negmas.preferences.value_fun import LinearFun, IdentityFun, AffineFun

# create negotiation agenda (issues)
issues = [
    make_issue(name="price", values=10),
    make_issue(name="quantity", values=(1, 11)),
    make_issue(name="delivery_time", values=10),
]

# create the mechanism
session = SAOMechanism(issues=issues, n_steps=20)

# define buyer and seller utilities
seller_utility = LUFun(
    values=[IdentityFun(), LinearFun(0.2), AffineFun(-1, bias=9.0)],
    outcome_space=session.outcome_space,
)

buyer_utility = LUFun(
    values={
        "price": AffineFun(-1, bias=9.0),
        "quantity": LinearFun(0.2),
        "delivery_time": IdentityFun(),
    },
    outcome_space=session.outcome_space,
)

# create and add buyer and seller negotiators
session.add(TimeBasedConcedingNegotiator(name="buyer"), preferences=buyer_utility)
session.add(TimeBasedConcedingNegotiator(name="seller"), ufun=seller_utility)

# run the negotiation and show the results
print(session.run())
```

--------------------------------

### Declaring Abstract Initialization and Step Methods (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Specifies the `init` and `step` methods as abstract within the `Person` class, forcing subclasses to provide implementations for agent initialization and per-step logic, overriding the default non-abstract behavior in the base `Agent` class.

```python
@abstractmethod
    def step(self):
        ...

    @abstractmethod
    def init(self):
        ...
```

--------------------------------

### Import Core NegMAS and Standard Libraries (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Imports essential classes and functions from the NegMAS library and standard Python modules required for building and running agent-based simulations and negotiations.

```python
from abc import abstractmethod, ABC
from collections import defaultdict
from random import shuffle, random, sample, randint

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
from negmas import (
    Action,
    Agent,
    NegotiatorMechanismInterface,
    AgentWorldInterface,
    Breach,
    Contract,
    Issue,
    make_issue,
    LinearUtilityFunction,
    MechanismState,
    Negotiator,
    RandomNegotiator,
    RenegotiationRequest,
    SAONegotiator,
    UtilityFunction,
    World,
)
from negmas.serialization import to_flat_dict
from typing import Callable, List, Optional, Set, Dict, Any, Collection
```

--------------------------------

### Handle Contract Signing - Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Implements the `on_contract_signed` callback to record the contract for execution at the next step, storing it in the `_contracts` mapping keyed by the execution step.

```python
    self._contracts[self.current_step + 1].append(contract)
```

--------------------------------

### Configuring and Running Negotiation with Modified Utility (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Defines a new utility function for the seller, giving significantly more weight to the 'delivery_time' issue. It then initializes a new SAO negotiation mechanism, adds the buyer and seller (with the new utility function), and runs the negotiation simulation, printing the final state.

```python
seller_utility = LUFun(
    values={
        "price": IdentityFun(),
        "quantity": LinearFun(0.2),
        "delivery_time": AffineFun(-1, bias=9),
    },
    weights={"price": 1.0, "quantity": 1.0, "delivery_time": 10.0},
    outcome_space=session.outcome_space,
)

session = SAOMechanism(issues=issues, n_steps=50)
session.add(TimeBasedConcedingNegotiator(name="buyer"), ufun=buyer_utility)
session.add(TimeBasedConcedingNegotiator(name="seller"), ufun=seller_utility)
print(session.run())
```

--------------------------------

### Run Simple Negotiation Simulation (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

This code snippet sets up and runs a negotiation session using the negmas library. It configures a seller using the TimeBasedConcedingNegotiator with a linear offering curve, runs the simulation, and then plots the results.

```python
TimeBasedConcedingNegotiator(name="seller", offering_curve="linear"),
        ufun=seller_utility,
    )
    session.run()
    session.plot(ylimits=(0.0, 1.01), show_reserved=False)
    plt.show()
```

--------------------------------

### Normalizing Utility Functions and Running Session (50 Steps)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Scales both seller and buyer utility functions to a maximum of 1.0, initializes a negotiation session with 50 steps, adds time-based conceding negotiators, runs the simulation, and plots the normalized results.

```python
seller_utility = seller_utility.scale_max(1.0)
buyer_utility = buyer_utility.scale_max(1.0)
session = SAOMechanism(issues=issues, n_steps=50)
session.add(TimeBasedConcedingNegotiator(name="buyer"), ufun=buyer_utility)
session.add(TimeBasedConcedingNegotiator(name="seller"), ufun=seller_utility)
session.run()
session.plot(ylimits=(0.0, 1.01), show_reserved=False)
plt.show()
```

--------------------------------

### Initializing World Parameters in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/05.develop_new_simulation.rst

Sets key parameters for the base World class constructor, including the AWI type, negotiation quota, force signing, and default signing delay. This configures the simulation environment.

```python
kwargs["awi_type"] = AWI
kwargs["negotiation_quota_per_step"] = kwargs.get("negotiation_quota_per_step", 8)
kwargs["force_signing"] = True
kwargs["default_signing_delay"] = 0
super().__init__(*args, **kwargs)
```

--------------------------------

### Defining Abstract Agent Initialization and Step Methods in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/05.develop_new_simulation.rst

Defines the abstract `init` and `step` methods that must be implemented by any agent compatible with the TripsWorld simulation. These methods are called for agent initialization (after AWI creation) and at each simulation step, respectively, forcing all `Person` based agents to provide an implementation.

```python
@abstractmethod
def step(self):
    ...


@abstractmethod
def init(self):
    ...
```

--------------------------------

### Printing Negotiation Trace - IPython

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/getting_started.rst

Demonstrates how to access and print the detailed history of offers and actions during a negotiation session using the 'extended_trace' property of the negotiation mechanism object.

```IPython
# negotiation history
print(mechanism.extended_trace)
```

--------------------------------

### Checking Outcome Range in NegMAS

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Demonstrates how to use the `outcome_in_range` function to check if specific outcomes fall within a defined range, showing examples of both valid and invalid outcomes.

```python
outcome1 = {"The Problem": "to be", "number of items": 5, "cost": 0.15}
outcome2 = {"The Problem": "to be", "number of items": 10, "cost": 0.15}
[
    outcome_in_range(outcome1, range1),  # True
    outcome_in_range(outcome2, range1),  # False
]
```

--------------------------------

### Displaying Negotiate CLI Help (Console)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/scripts.rst

This command displays the help message for the `negotiate` command-line interface, listing all available options and usage instructions.

```console
$ negotiate --help
```

--------------------------------

### Get Executable Contracts for Current Step - Python

Source: https://github.com/yasserfarouk/negmas/blob/master/notebooks/tutorials/05.develop_new_simulation.ipynb

Retrieves the list of contracts from the internal _contracts mapping that are scheduled to be executed at the current simulation step. This implements the executable_contracts callback.

```python
return self._contracts[self.current_step]
```

--------------------------------

### Running Basic Nash Bargaining Game Simulation in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/04.develop_new_mechanism.rst

Demonstrates how to set up and run a simple Nash bargaining game simulation using the negmas library. It initializes the game, creates linear utility functions, adds two Nash negotiators, runs the simulation, and prints the resulting agreement.

```python
m = NashBargainingGame()
u1 = LinearUtilityFunction([1, 0], reserved_value=0.0, outcome_space=m.outcome_space)
u2 = LinearUtilityFunction([0, 1], reserved_value=0.0, outcome_space=m.outcome_space)
m.add(NashNegotiator(ufun=u1, name="a1"))
m.add(NashNegotiator(ufun=u2, name="a2"))
result = m.run()
print(f"Agreement: {result.agreement}")
```

--------------------------------

### Generating Random Valid/Invalid Values (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Demonstrates using `rand_valid()` and `rand_invalid()` methods to get random values that are either within or outside the issue's valid range.

```python
[
    [issue1.rand_valid(), issue1.rand_invalid()],
    [issue3.rand_valid(), issue3.rand_invalid()],
    [issue4.rand_valid(), issue4.rand_invalid()],
]
```

--------------------------------

### Define Abstract Init and Step Methods (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/notebooks/tutorials/05.develop_new_simulation.ipynb

Specifies the abstract `init` and `step` methods that must be implemented by any agent based on the `Person` class. `init` is called for initialization, and `step` is called at each simulation step.

```python
@abstractmethod
    def step(self):
        ...

    @abstractmethod
    def init(self):
        ...
```

--------------------------------

### Creating Issues in NegMAS 0.8 (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/upgrade_guide.rst

In NegMAS 0.8, issues were created directly using the constructor of the monolithic Issue class. This approach is replaced in 0.9 by a factory function.

```python
issue = Issue(...)
```

--------------------------------

### Initializing SAOMechanism in NegMAS (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Instantiates the SAOMechanism, a NegMAS class implementing the Stacked Alternating Offers Protocol. Configures it with 10 possible outcomes and a maximum of 100 negotiation steps (rounds).

```python
session = SAOMechanism(outcomes=10, n_steps=100)
```

--------------------------------

### Implement Get Private State in Negmas TripsWorld (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/05.develop_new_simulation.rst

Defines the `get_private_state` method, which provides an agent with its private information. In `TripsWorld`, this is the agent's total accumulated utility.

```python
def get_private_state(self, agent: Agent) -> dict:
    """What is the information available to agents? total utility points"""
    return dict(total_utility=self._total_utility[agent.id])
```

--------------------------------

### Running a Simulation with Random Agents (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/06.develop_new_agent.rst

Demonstrates how to initialize the TripsWorld simulation, add multiple instances of the RandomPerson agent to it, and then run the simulation for a specified number of steps while displaying progress.

```Python
world = TripsWorld(n_steps=10, construct_graphs=True)
for i in range(5):
    world.join(RandomPerson(name=f"a{i}"))
world.run_with_progress()
```

--------------------------------

### Representing Outcomes in NegMAS 0.8 (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/upgrade_guide.rst

In NegMAS 0.8, outcomes could be represented using tuples, dictionaries, or custom OutcomeType objects. NegMAS 0.9 simplifies this by requiring all outcomes to be tuples.

```python
w = (0, 1)
```

```python
w = dict(price=0, quantity=1)
```

```python
w = O(price=0, quantity=1)
```

--------------------------------

### Download NegMAS Genius Bridge Directly (Windows PowerShell)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Downloads the Genius bridge JAR file directly from the provided URL using Invoke-WebRequest and saves it to the specified location within the user's home directory. This is an alternative to the negmas genius-setup command for Windows using PowerShell.

```powershell
Invoke-WebRequest -Uri https://yasserfarouk.github.io/files/geniusbridge.jar -OutFile $HOME\negmas\files\geniusbridge.jar
```

--------------------------------

### Getting Agent Private State in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Defines the `get_private_state` method, which specifies what information is available to an agent through its `awi.state`. In this case, it returns a dictionary containing the agent's total accumulated utility.

```python
    def get_private_state(self, agent: Agent) -> dict:
        """What is the information available to agents? total utility points"""
        return dict(total_utility=self._total_utility[agent.id])
```

--------------------------------

### Providing Default Negotiation Lifecycle Callbacks (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Includes default, do-nothing implementations for various callback methods related to the negotiation lifecycle (request rejection/acceptance, negotiation failure/success, contract execution/breach), allowing `Person` subclasses to optionally override them for specific behavior.

```python
def on_neg_request_rejected(self, req_id: str, by: Optional[List[str]]):
        ...
    def on_neg_request_accepted(self, req_id: str, mechanism: AgentMechanismInterface):
        ...
    def on_negotiation_failure( self, partners: List[str], annotation: Dict[str, Any],
        mechanism: AgentMechanismInterface, state: MechanismState,):
        ...
    def on_negotiation_success( self, contract: Contract, mechanism: AgentMechanismInterface):
        ...
    def set_renegotiation_agenda(
        self, contract: Contract, breaches: List[Breach]) -> Optional[RenegotiationRequest]:
        ...
    def respond_to_renegotiation_request(
        self, contract: Contract, breaches: List[Breach], agenda: RenegotiationRequest) -> Optional[Negotiator]:
        ...
    def on_contract_executed(self, contract: Contract):
        ...
    def on_contract_breached(self, contract: Contract, breaches: List[Breach]):
        ...
```

--------------------------------

### Download NegMAS Genius Bridge Directly (Linux/macOS bash)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Downloads the Genius bridge JAR file directly from the provided URL using curl and saves it to the specified location within the user's home directory, creating necessary directories if they don't exist. This is an alternative to the negmas genius-setup command for Linux and macOS.

```bash
curl https://yasserfarouk.github.io/files/geniusbridge.jar --create-dirs -o $HOME/negmas/files/geniusbridge.jar
```

--------------------------------

### Adding Optional Destination to SAO Negotiator Propose Method in NegMAS 0.11

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/upgrade_guide.rst

NegMAS 0.11 modifies the `propose` function for SAONegotiators to include an optional `dest` parameter, allowing specification of the negotiation destination.

```Python
def propose(self, state)
```

```Python
def propose(self, state, dest=None)
```

--------------------------------

### Running a Basic NegMAS Negotiation

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

This snippet initializes a ParallelResponseMechanism, adds two LimitedOutcomesNegotiator agents with specific acceptable outcomes, runs the negotiation process, and accesses the final agreement from the mechanism state.

```python
p = ParallelResponseMechanism(outcomes=6, n_steps=10)
p.add(LimitedOutcomesNegotiator(name="seller", acceptable_outcomes=[(2,), (3,), (5,)]))
p.add(LimitedOutcomesNegotiator(name="buyer", acceptable_outcomes=[(1,), (4,), (3,)]))
state = p.run()
p.state.agreement
```

--------------------------------

### Updating SAO Negotiator Respond Method in NegMAS 0.10

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/upgrade_guide.rst

In NegMAS 0.10, the `respond` method for SAO negotiators no longer directly receives the `offer` parameter. The current offer can now be accessed through `state.current_offer` within the method.

```Python
def respond(self,state, offer,...)
```

```Python
def respond(self, state, ...)
```

--------------------------------

### Running NegMAS Session with Direct GeniusNegotiator Instantiation (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

This example illustrates running a negotiation session between two Genius agents by directly instantiating the `GeniusNegotiator` class for each agent. It explicitly provides the `java_class_name` for the underlying Genius agent.

```ipython3
from negmas.genius import GeniusNegotiator

session = scenario.make_session(time_limit=10)
session.add(
    GeniusNegotiator(
        java_class_name="agents.anac.y2015.Atlas3.Atlas3",
        preferences=scenario.ufuns[0],
        name="Atlas3",
    )
)
session.add(
    GeniusNegotiator(
        java_class_name="agents.anac.y2010.AgentK.Agent_K",
        preferences=scenario.ufuns[1],
        name="AgentK",
    )
)
session.run()
session.plot()
plt.show()
```

--------------------------------

### Calling Abstract Negotiation Handler from Internal Method (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Shows how the internal `_respond_to_negotiation_request` method in the `Person` base class delegates the actual handling of negotiation requests to the abstract `respond_to_negotiation_request` method, simplifying the interface for subclasses.

```python
return self.respond_to_negotiation_request(initiator, partners, mechanism)
```

--------------------------------

### Run NegMAS Genius Bridge Directly (bash)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/02.integrating_with_genius.rst

Executes the Genius bridge JAR file directly using the Java runtime. This is an alternative way to start the bridge process if the negmas genius command does not work or if you prefer to run it manually.

```bash
java -jar $HOME/negmas/files/geniusbridge.jar
```

--------------------------------

### Creating Issues with make_issue (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

This snippet demonstrates how to create Issue objects in NegMAS using the `make_issue` function. It shows examples of creating an issue with a randomly assigned name and another with a specified name, both using a list of strings as possible values.

```python
# an issue with randomly assigned name
issue1 = make_issue(values=["to be", "not to be"])
print(issue1)
# an issue with given name:
issue2 = make_issue(values=["to be", "not to be"], name="The Problem")
print(issue2)
```

--------------------------------

### Creating Issues in NegMAS 0.9 (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/upgrade_guide.rst

In NegMAS 0.9, issues should be created using the make_issue factory function, which handles the creation of the appropriate specific issue type (e.g., OrdinalIssue, ContinuousIssue). This replaces the direct use of the Issue constructor from 0.8.

```python
issue = make_issue(...)
```

--------------------------------

### Import All NegMAS Components (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/notebooks/tutorials/05.develop_new_simulation.ipynb

This snippet provides a shorthand way to import all publicly available components from the `negmas` library using the wildcard import `*`. This is often used for convenience in scripts or tutorials but can make it harder to track dependencies.

```python
from negmas import *
```

--------------------------------

### Viewing Full Negotiation Trace - IPython

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Executes a command in an IPython environment to retrieve the complete history of offers and proposers throughout the negotiation session.

```ipython
session.extended_trace
```

--------------------------------

### Running an SAO Negotiation Session in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/README.rst

This code demonstrates how to set up and run a simple Simultaneous Alternating Offers (SAO) negotiation session using negmas. It initializes a session, creates multiple agents with random preferences, adds them to the session, and executes the negotiation.

```python
import random
from negmas import SAOMechanism, AspirationNegotiator, MappingUtilityFunction

session = SAOMechanism(outcomes=10, n_steps=100)
negotiators = [AspirationNegotiator(name=f"a{_}") for _ in range(5)]
for negotiator in negotiators:
    session.add(
        negotiator, preferences=MappingUtilityFunction(lambda x: random.random() * x[0])
    )
session.run()
```

--------------------------------

### Combining Global and Local Utility Functions with HyperRectangleUtilityFunction

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

This example illustrates defining a `HyperRectangleUtilityFunction` that combines a global utility function with two local functions defined over specific outcome ranges. It shows how to use `outcome_ranges`, `utilities`, and `weights` parameters to specify different utility behaviors across the outcome space.

```python
f = HyperRectangleUtilityFunction(
    outcome_ranges=[
        None,
        {0: (1.0, 2.0), 1: (1.0, 2.0)},
        {0: (1.4, 2.0), 2: (2.0, 3.0)},
    ],
    utilities=[5.0, 2.0, lambda x: 2 * x[2] + x[0]],
    weights=[1, 0.5, 2.5],
)
```

--------------------------------

### SAONegotiator Required `propose` Method Signature (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/03.develop_new_negotiator.rst

This snippet shows the required signature for the `propose` abstract method that must be implemented by any class inheriting from `SAONegotiator`. This method is called by the mechanism to get the negotiator's proposed outcome for the current negotiation state. It takes the current `SAOState` and should return an `Outcome`.

```python
def proposed(self, state: SAOState) -> Outcome:
       ...
```

--------------------------------

### Run Negotiation with Possible Agreement (IPython)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Sets up a `NewParallelResponseMechanism` with two `LimitedOutcomesNegotiator` agents whose acceptable outcomes share a common outcome ((3,)). Runs the negotiation to demonstrate that it can reach an agreement.

```python
p = NewParallelResponseMechanism(outcomes=6, n_steps=6)
p.add(LimitedOutcomesNegotiator(name="seller", acceptable_outcomes=[(3,), (0,), (5,)]))
p.add(LimitedOutcomesNegotiator(name="buyer", acceptable_outcomes=[(1,), (4,), (3,)]))
p.run()
print(f"Agreement: {p.state.agreement}")
show_history(p)
```

--------------------------------

### Running Negotiation Session (5000 Steps)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Initializes and runs a negotiation session with a significantly increased number of steps (5000) to observe the effect of longer negotiation time on the outcome, then plots the result with normalized utility limits.

```python
session = SAOMechanism(issues=issues, n_steps=5000)

session.add(TimeBasedConcedingNegotiator(name="buyer"), ufun=buyer_utility)
session.add(TimeBasedConcedingNegotiator(name="seller"), ufun=seller_utility)
session.run()
session.plot(ylimits=(0.0, 1.01), show_reserved=False)
plt.show()
```

--------------------------------

### Example Negotiation Data Tuples (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/getting_started.rst

These tuples illustrate the structure used to log or represent data points during a negotiation process. Each tuple contains three elements: the negotiation round number (integer), the unique identifier of the agent involved (string), and a value or outcome associated with that agent in that round (tuple, potentially representing a single value).

```python
(1, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (49,)),
(1, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (4,)),
(2, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (49,)),
(2, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (7,)),
(3, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (49,)),
(3, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (9,)),
(4, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (49,)),
(4, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (11,)),
(5, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (49,)),
(5, 'buyer-953acaf8-4227-4d51-a652-8626f799fa76', (14,)),
(6, 'seller-e3614ef9-6d24-442a-9332-b15342ffa1e4', (49,))
```

--------------------------------

### Initializing Linear Additive Utility Function in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Demonstrates the initialization of a LinearAdditiveUtilityFunction using a list of explicit outcomes and a list of value functions for each issue.

```python
u3 = LinearAdditiveUtilityFunction(
    outcomes=[(0, 0), (0, 1), (1, 0), (1, 1)],
    values=[lambda x: x, lambda x: x, lambda x: x],
)
```

--------------------------------

### Implementing Nash Bargaining Game Mechanism in NegMAS (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/04.develop_new_mechanism.rst

Defines the `NashBargainingGame` class, inheriting from `Mechanism`, to implement the Nash Bargaining Game protocol. It overrides `__init__` for setup, `add` to handle negotiator addition and utility function storage, `is_feasible` to check outcome validity, and `__call__` to execute the single round of the game where negotiators propose outcomes and feasibility is checked.

```python
class NashBargainingGame(Mechanism):\n    """A mechanism representing the nash bargaining game"""\n\n    def __init__(self, **kwargs):\n        kwargs.update(dict(n_steps=1, max_n_negotiators=2, dynamic_entry=False))\n        super().__init__(**kwargs, issues=[make_issue((0.0, 1.0))])\n        self.add_requirements(dict(propose_for_self=True))\n        self.ufuns: List[UtilityFunction] = []\n\n    def add(\n        self,\n        negotiator: Negotiator,\n        *,\n        preferences: Preferences | None = None,\n        **kwargs,\n    ) -> Optional[bool]:\n        added = super().add(negotiator, preferences=preferences, role=None, **kwargs)\n        if added:\n            self.ufuns.append(self.negotiators[-1].ufun)\n\n    def is_feasible(self, outcome: Tuple[float]):\n        """Tests feasibility of outcomes.\n\n        The default implementation tests that the of all utilities assigned to all negotiators is less than 1.0.\n        """\n        return sum(u(outcome) for u in self.ufuns) <= (1.0 + 1e-3)\n\n    def __call__(self, state, action=None) -> MechanismStepResult:\n        """One round of the mechanism"""\n        if len(self.negotiators) != 2:\n            state.has_error = True\n            state.error_details = f"Got {len(self.negotiators)} negotiators!!"\n            state.broken = True\n            return MechanismStepResult(state=state)\n        outcome = tuple(\n            n.propose_for_self(self.ufuns, i) for i, n in enumerate(self.negotiators)\n        )\n        if self.is_feasible(outcome):\n            state.agreement = outcome\n        return MechanismStepResult(state=state)
```

--------------------------------

### Using a NegMAS Mechanism with Custom State

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

This snippet demonstrates using the `NewParallelResponseMechanism` defined previously. It initializes the mechanism, adds agents, runs the negotiation, and prints the final agreement, showing that the custom state is correctly used.

```python
p = NewParallelResponseMechanism(outcomes=6, n_steps=10)
p.add(LimitedOutcomesNegotiator(name="seller", acceptable_outcomes=[(2,), (3,), (5,)]))
p.add(LimitedOutcomesNegotiator(name="buyer", acceptable_outcomes=[(1,), (4,), (3,)]))
p.run()
print(f"Agreement: {p.state.agreement}")
```

--------------------------------

### Running Session with Linear Concession (5000 Steps)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

Configures both buyer and seller negotiators to use a linear concession curve, runs the session for 5000 steps, and plots the outcome to analyze the impact of faster, linear concession on the negotiation result.

```python
session = SAOMechanism(issues=issues, n_steps=5000)
session.add(
    TimeBasedConcedingNegotiator(name="buyer", offering_curve="linear"),
    ufun=buyer_utility,
)
session.add(
    TimeBasedConcedingNegotiator(name="seller", offering_curve="linear"),
    ufun=seller_utility,
)
session.run()
session.plot(ylimits=(0.0, 1.01), show_reserved=False)
plt.show()
```

--------------------------------

### Calculating Buyer Utility using dict2outcome in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Demonstrates calculating buyer utility by converting a dictionary representation of an outcome to the required tuple format using the dict2outcome helper function.

```python
buyer_utility(
    dict2outcome(
        {"price": 1.8, "number of items": 3, "delivery": "delivered"},
        issues=buyer_utility.issues,
    )
)
```

```output
0.7
```

--------------------------------

### Defining World Data Members in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/notebooks/05.develop_new_simulation.ipynb

Shows the definition of key data members within the world class (`_contracts`, `_total_utility`, `_ufuns`, `_breach_prob`) using Python dictionaries and defaultdicts to track contracts, agent utility, utility functions, and breach probabilities.

```python
        self._contracts: Dict[int, List[Contract]] = defaultdict(list)
        self._total_utility: Dict[str, float] = defaultdict(float)
        self._ufuns: Dict[str, UtilityFunction] = dict()
        self._breach_prob: Dict[str, float] = dict()
```

--------------------------------

### Running a Negotiation Simulation in Python

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/tutorials/01.running_simple_negotiation.rst

This snippet initializes an SAO (Single Issue, Alternating Offers) negotiation mechanism, creates five time-based conceding negotiators, assigns them random utility functions, and runs the negotiation session.

```python
from negmas import SAOMechanism, TimeBasedConcedingNegotiator, MappingUtilityFunction
import random  # for generating random ufuns

random.seed(0)  # for reproducibility

session = SAOMechanism(outcomes=10, n_steps=100)
negotiators = [TimeBasedConcedingNegotiator(name=f"a{_}") for _ in range(5)]
for negotiator in negotiators:
    session.add(
        negotiator,
        preferences=MappingUtilityFunction(
            lambda x: random.random() * x[0], outcome_space=session.outcome_space
        ),
    )

print(session.run())
```

--------------------------------

### Importing All Classes from negmas (Not Recommended) (Python)

Source: https://github.com/yasserfarouk/negmas/blob/master/docs/overview.rst

Shows how to import all classes and functions from the main negmas package and selected helper modules using the '*' wildcard. This method is generally not recommended due to potential namespace pollution.

```python
from negmas import *
from negmas.helpers import *
from negmas.helpers.prob import *
```
Tokens:
Raw