negotiate CLI

The negotiate CLI provides a simple way for running negotiations, plotting them, and saving their statistics.

Installation

The negotiate command is automatically available after installing NegMAS:

$ pip install negmas

Basic Usage

Run a simple negotiation with default settings:

$ negotiate

Run with a specific scenario:

$ negotiate --scenario path/to/scenario.yml

You can find out about all the available options by running:

$ negotiate --help

Command Reference

negotiate

negotiate Usage: negotiate [OPTIONS] ╭─ Options ─────────────────────────────────────────────────────╮ │--scenario-S<str>The scenario to         │ │negotiate about. Can    │ │specify as: scenario    │ │name (e.g. CameraB),    │ │source@name (e.g.       │ │negmas@CameraB), or a   │ │file path               │ │[default: (Generate A   │ │new Scenario)]          │ │--install-completionInstall completion for  │ │the current shell.      │ │--show-completionShow completion for the │ │current shell, to copy  │ │it or customize the     │ │installation.           │ │--helpShow this message and   │ │exit.                   │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Basic Options ───────────────────────────────────────────────╮ │--protocol,--…-m<str>The protocol  │ │(Mechanism to │ │use)          │ │[default: SAO]│ │--negotiator,…-n,-a<str>Negotiator    │ │(agent) type. │ │Can specify   │ │as: registry  │ │short name    │ │(e.g.         │ │AspirationNeg…│ │source@name   │ │(e.g.         │ │negmas@Aspira…│ │registry key  │ │(e.g.         │ │AspirationNeg…│ │full Python   │ │path (e.g.    │ │negmas.sao.As…│ │or with       │ │prefixes:     │ │genius:       │ │(Genius       │ │negotiators   │ │via bridge),  │ │anl: (ANL     │ │agents), boa: │ │(BOA          │ │negotiators), │ │map: (MAP     │ │negotiators), │ │llm: (LLM     │ │negotiators   │ │from          │ │negmas-llm),  │ │negolog:      │ │(Negolog      │ │negotiators   │ │from          │ │negmas-negolo…│ │ga: (Genius   │ │Agents from   │ │negmas-genius…│ │To use an     │ │adapter, put  │ │the adapter   │ │name first    │ │separated by a│ │slash (e.g.   │ │TAUAdapter/As…│ │Use           │ │--list-agents│ │to see all    │ │available     │ │registry      │ │entries.      │ │[default:     │ │AspirationNeg…│ │NaiveTitForTa…│ │--extend-nego…-EExtend the    │ │negotiator    │ │list to cover │ │all ufuns     │ │--truncate-uf…-TUse the first │ │n. negotiator │ │ufuns only    │ │--params<str>Mechanism     │ │initialization│ │parameters as │ │comma-separat…│ │`key=value`   │ │pairs.        │ │--share-ufuns--no-share-u…Share partner │ │ufuns using   │ │private-data. │ │[default:     │ │no-share-ufun…│ │--share-reser…--no-share-r…Share partner │ │reserved-valu…│ │using         │ │private-data. │ │[default:     │ │no-share-rese…│ │--in-geniusRun the       │ │negotiation   │ │natively in   │ │Genius (all   │ │agents must be│ │Genius agents)│ │--port-p<int>Port for      │ │Genius bridge │ │(default:     │ │25337)        │ │[default:     │ │25337]        │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Deadline ────────────────────────────────────────────────────╮ │--steps-s<int>Number of Steps allowed │ │in the negotiation      │ │--time,--timelimit-t<float>Number of Seconds       │ │allowed in the          │ │negotiation             │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Scenario Overrides ──────────────────────────────────────────╮ │--reserved-r<float>Reserved values│ │to override the│ │ones in the    │ │scenario. Must │ │be the same    │ │length as the  │ │ufuns.         │ │--fraction-f<float>Rational       │ │factions to use│ │for generating │ │reserved values│ │to override the│ │ones in the    │ │scenario. Must │ │be the same    │ │length as the  │ │ufuns.         │ │--discount-d--no-discount-DLoad Discount  │ │Factor         │ │[default:      │ │discount]      │ │--normalize/-NNormalize ufuns│ │to the range   │ │(0-1)          │ │[default: True]│ ╰───────────────────────────────────────────────────────────────╯ ╭─ Generated Scenario ──────────────────────────────────────────╮ │--issues-i<int>N. Issues│ │--values-min<int>Minimum      │ │allowed n.   │ │values per   │ │issue        │ │[default: 2] │ │--values-max<int>Maximum      │ │allowed n.   │ │values per   │ │issue        │ │[default: 50]│ │--size-z<int>Sizes of     │ │issues in    │ │order        │ │(overrides   │ │values-min,  │ │values-max)  │ │--reserved-va…<float>Min Allowed  │ │Reserved     │ │value        │ │[default:    │ │0.0]         │ │--reserved-va…<float>Max allowed  │ │reserved     │ │value        │ │[default:    │ │1.0]         │ │--rational-R--irrational…-IGurantee Some│ │Rational     │ │Outcomes     │ │[default:    │ │rational]    │ │--rational-fr…-F<float>Reservation  │ │fractions    │ │--reservation…<str>Reservation  │ │value        │ │selector if  │ │both         │ │reserved-val…│ │and          │ │rational-fra…│ │are given:   │ │min|max|firs…│ │[default:    │ │min]         │ │--issue-name<str>Issue Names│ │--os-name<str>Outcome Space│ │Name         │ │--ufun-names<str>Names of     │ │Ufuns        │ │--numeric--no-numericNumeric      │ │Issues       │ │[default:    │ │no-numeric]  │ │--linear--non-linearLinear Ufuns │ │[default:    │ │linear]      │ │--pareto-gene…<str>One or more  │ │Pareto       │ │Generator    │ │methods. See │ │negmas.prefe…│ │for possible │ │values       │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Output control ──────────────────────────────────────────────╮ │--python-class-identif…<str>Python class identifier│ │in the saved files     │ │[default:              │ │__python_class__]      │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Output Control ──────────────────────────────────────────────╮ │--verbose-vMake verbose│ │--verbosity<int>Verbosity     │ │level         │ │(higher=more  │ │verbose)      │ │[default: 0]  │ │--progress--no-progressShow Progress │ │Bar           │ │[default:     │ │progress]     │ │--history--no-historyPrint History │ │[default:     │ │no-history]   │ │--stats--no-statsGenerate      │ │Statistics    │ │[default:     │ │stats]        │ │--rank-stats--no-rank-sta…Generate Rank │ │Statistics    │ │--compact-sta…-c--detailed-st…-CShow distances│ │[default:     │ │compact-stats]│ ╰───────────────────────────────────────────────────────────────╯ ╭─ Plotting ────────────────────────────────────────────────────╮ │--plot--no-plotGenerate Plot │ │[default:     │ │plot]         │ │--only2d-2--with-offers-0Only 2D Plot  │ │[default:     │ │with-offers]  │ │--plot-backend<str>[Deprecated]  │ │Backend used  │ │for plotting. │ │Now uses      │ │plotly.       │ │--plot-intera…--no-plot-in…[Deprecated]  │ │Plotly is     │ │always        │ │interactive.  │ │[default:     │ │plot-interact…│ │--plot-show--no-plot-sh…Show the plot │ │[default:     │ │plot-show]    │ │--simple-offe…--no-simple-…Simple Offers │ │View          │ │--annotations--no-annotat…Show          │ │Annotations   │ │[default:     │ │no-annotation…│ │--agreement--no-agreeme…Show Agreement│ │[default:     │ │no-agreement] │ │--pareto-dist--no-pareto-…Show Pareto   │ │Distance      │ │[default:     │ │pareto-dist]  │ │--nash-dist--no-nash-di…Show Nash     │ │Distance      │ │[default:     │ │nash-dist]    │ │--kalai-dist--no-kalai-d…Show Kalai    │ │Distance      │ │[default:     │ │kalai-dist]   │ │--max-welfare…--no-max-wel…Show Max      │ │Welfare       │ │Distance      │ │[default:     │ │max-welfare-d…│ │--max-rel-wel…--no-max-rel…Show Max      │ │Relative      │ │Welfare       │ │Distance      │ │[default:     │ │no-max-rel-we…│ │--end-reason--no-end-rea…Show End      │ │Reason        │ │[default:     │ │end-reason]   │ │--show-reserv…--no-show-re…Show Reserved │ │Value Lines   │ │[default:     │ │show-reserved]│ │--total-time--no-total-t…Show Time     │ │Limit         │ │[default:     │ │total-time]   │ │--relative-ti…--no-relativ…Show Relative │ │Time          │ │[default:     │ │relative-time]│ │--show-n-steps--no-show-n-…Show N. Steps │ │[default:     │ │show-n-steps] │ │--darkUse dark theme│ │for plots     │ │--color-blindUse           │ │color-blind   │ │friendly      │ │colors        │ │--plot-path<path>Path to save  │ │the plot to.  │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Saving to Disk ──────────────────────────────────────────────╮ │--save-path<path>Path to save    │ │results to      │ │[default: (Do   │ │not Save)]      │ │--save-history--no-save-hist…Save Negotiation│ │Histroy         │ │[default:       │ │save-history]   │ │--save-stats--no-save-statsSave Statistics │ │[default:       │ │save-stats]     │ │--save-type<str>Scenario        │ │Format:yml|xml  │ │[default: yml]  │ │--save-compact--no-save-comp…Compact file    │ │[default:       │ │save-compact]   │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Advanced ────────────────────────────────────────────────────╮ │--fast--no-fastAvoid slow     │ │operations     │ │--path<path>One or more    │ │extra paths to │ │look for       │ │negotiator and │ │mechanism      │ │classes.       │ │--raise-except…--no-raise-exc…Raise          │ │Exceptions on  │ │Failure        │ │[default:      │ │no-raise-excep…│ ╰───────────────────────────────────────────────────────────────╯ ╭─ Registry Options ────────────────────────────────────────────╮ │--list-agentsList available agents  │ │from the registry and  │ │exit (can filter by    │ │--agent-source)        │ │--list-scenariosList available         │ │scenarios from the     │ │registry and exit (can │ │filter by              │ │--scenario-source)     │ │--info,--info-agent<str>Display detailed       │ │information about a    │ │negotiator and exit    │ │(e.g.,                 │ │'AspirationNegotiator' │ │or                     │ │'negmas@AspirationNego…│ │--info-scenario<str>Display detailed       │ │information about a    │ │scenario and exit      │ │(e.g., 'CameraB' or    │ │'negmas@CameraB')      │ │--agent-source,--source<str>Filter agents by source│ │(e.g., 'negmas',       │ │'anl'). Used with      │ │--list-agents.         │ │--scenario-source<str>Filter scenarios by    │ │source (e.g., 'negmas',│ │'genius'). Used with   │ │--list-scenarios.      │ │--refresh-registryReload the registry    │ │from disk before       │ │running                │ │--on-multiple-matches<str>What to do when        │ │multiple registry      │ │entries match a short  │ │name: 'fail' (show     │ │table and exit), 'warn'│ │(show table but        │ │continue), 'silent'    │ │(use first match       │ │silently)              │ │[default: warn]        │ ╰───────────────────────────────────────────────────────────────╯

Available Negotiators

The negotiate command supports multiple types of negotiators through prefix-based selection:

Negotiator Prefixes

Prefix

Description

(none)

NegMAS native negotiators (e.g., AspirationNegotiator)

genius:

Java Genius agents via JVM bridge (e.g., genius:HardHeaded)

anl:

ANL competition agents from the anl-agents package

boa:

BOA negotiators with custom components (e.g., boa:offering=GTimeDependentOffering,acceptance=GACNext)

map:

MAP negotiators with custom components

llm:

LLM-based negotiators from negmas-llm package

negolog:

Prolog-based negotiators from negmas-negolog package

ga:

Genius Agents from negmas-genius-agents package

NegMAS Native Negotiators

These are pure Python negotiators that work out of the box without any external dependencies.

Time-Based Negotiators

These negotiators follow a time-dependent concession strategy, offering decreasing utility over time.

Negotiator

Description

AspirationNegotiator

The default time-based negotiator with configurable aspiration curve

BoulwareTBNegotiator

Concedes slowly (sub-linearly), making most concessions near the deadline

LinearTBNegotiator

Concedes at a constant rate throughout the negotiation

ConcederTBNegotiator

Concedes quickly (super-linearly), making most concessions early

Tit-for-Tat Negotiators

These negotiators base their concessions on the opponent’s behavior.

Negotiator

Description

NaiveTitForTatNegotiator

Mirrors opponent concessions without explicit opponent modeling

SimpleTitForTatNegotiator

Alias for NaiveTitForTatNegotiator

Other Native Negotiators

Negotiator

Description

ToughNegotiator

Only proposes and accepts the best outcome (hardliner strategy)

TopFractionNegotiator

Proposes and accepts only top-fraction outcomes

NiceNegotiator

Offers randomly and accepts everything (maximally cooperative)

RandomNegotiator

Makes random offers with configurable acceptance probability

RandomAlwaysAcceptingNegotiator

Random offers but accepts near-optimal outcomes

Offer-Oriented Negotiators

These negotiators consider partner offers when selecting their own offers.

Negotiator

Description

FirstOfferOrientedTBNegotiator

Considers the partner’s first offer

LastOfferOrientedTBNegotiator

Considers the partner’s most recent offer

BestOfferOrientedTBNegotiator

Considers the partner’s best offer so far

AdditiveParetoFollowingTBNegotiator

Follows Pareto frontier using additive weights

MultiplicativeParetoFollowingTBNegotiator

Follows Pareto frontier using multiplicative weights

Python-Native Genius BOA Negotiators (G-Prefix)

These are Python implementations of classic Genius agents, transcompiled from the original Java code. They use the BOA (Bidding, Opponent modeling, Acceptance) architecture and do NOT require the Java Genius bridge. All names are prefixed with G to distinguish them from the Java versions.

Classic Time-Dependent Agents

Negotiator

Description

GBoulware

Conservative strategy (e=0.2), concedes slowly near deadline

GConceder

Accommodating strategy (e=2.0), concedes quickly early on

GLinear

Constant concession rate (e=1.0)

GHardliner

Never concedes (e=0), always offers best outcome

ANAC Competition Winners and Notable Agents

Negotiator

Year

Description

GHardHeaded

2011

Winner. Boulware-style with frequency-based opponent modeling

GAgentK

2010

Top performer. Time-dependent with combined acceptance conditions

GAgentSmith

2010

Notable. Time-dependent with constant threshold acceptance

GNozomi

2010

Competitive. Boulware-style with previous-offer acceptance

GFSEGA

2010

Faculty of CS agent. Conceder with constant threshold

GCUHKAgent

2012

Winner. Conservative time-dependent with frequency opponent model

GAgentLG

2012

Notable. Time-dependent with max-based combined acceptance

GAgentX

2015

Notable. Adaptive time-dependent with window-based acceptance

Utility Agents

Negotiator

Description

GRandom

Random offers and accepts everything (baseline agent)

Genius Bridge Negotiators (Java)

These negotiators run actual Java Genius agents through a JVM bridge. They provide access to the full library of ~200 Genius agents but require additional setup.

Setup Requirements

Before using Genius bridge negotiators, you must:

  1. Install Java (JRE 8 or higher)

  2. Run the Genius setup command:

$ negmas genius-setup

  1. Start the Genius bridge (in a separate terminal or as a background process):

$ negmas genius

The bridge must be running whenever you use Genius negotiators.

Using Genius Negotiators

Genius negotiators are specified with the genius: prefix:

$ negotiate -n genius:HardHeaded -n genius:AgentK --steps 100

Some notable Genius negotiators include:

Negotiator

Year

Description

genius:HardHeaded

2011

ANAC 2011 winner, frequency-based opponent modeling

genius:CUHKAgent

2012

ANAC 2012 winner, handles discount factors well

genius:AgentK

2010

Top ANAC 2010 performer

genius:AgentSmith

2010

Frequency-based opponent modeling

genius:Nozomi

2010

Boulware-style negotiation

genius:Atlas3

2015

ANAC 2015 top performer

genius:ParsAgent

2016

ANAC 2016 top performer

genius:Caduceus

2016

Multi-party negotiation specialist

For a complete list of available Genius agents, see the negmas.genius.gnegotiators module.

Note: The G-prefixed negotiators (e.g., GHardHeaded) are Python-native and do not require the Genius bridge. They are recommended for most use cases due to better performance and simpler setup.

Note: The negotiate CLI will automatically attempt to start the Genius bridge if it is not running when you use the genius: prefix. If the bridge cannot be started, helpful instructions will be displayed.

External Package Negotiators

NegMAS supports negotiators from external packages through prefixes. These packages must be installed separately.

LLM Negotiators (negmas-llm)

Use large language models for negotiation:

$ pip install negmas-llm
$ negotiate -n llm:GPTNegotiator -n AspirationNegotiator --steps 50

Negolog Negotiators (negmas-negolog)

Use Prolog-based negotiation strategies:

$ pip install negmas-negolog
$ negotiate -n negolog:PrologNegotiator -n AspirationNegotiator --steps 50

Genius Agents (negmas-genius-agents)

Use pre-packaged Genius-style agents:

$ pip install negmas-genius-agents
$ negotiate -n ga:SomeAgent -n AspirationNegotiator --steps 50

Examples

Run a negotiation with 3 issues and 100 steps:

$ negotiate -i 3 -s 100

Run with specific negotiators:

$ negotiate -n AspirationNegotiator -n NaiveTitForTatNegotiator

Run with Python-native Genius agents (no bridge required):

$ negotiate -n GBoulware -n GConceder --steps 50

Run with ANAC competition winners:

$ negotiate -n GHardHeaded -n GCUHKAgent --steps 100

Run with Java Genius agents (requires bridge):

$ negmas genius &  # Start bridge in background
$ negotiate -n genius:HardHeaded -n genius:AgentK --steps 100

Run without plotting:

$ negotiate --no-plot

Save results to a specific path:

$ negotiate --save-path ./results

Run with a time limit of 60 seconds:

$ negotiate -t 60