yasserfarouk/negmas
yasserfarouk/negmas has 104 GitHub stars and 25 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and +2 in 15 days. Last checked 2026-11-18 04:02 UTC. Last push 2026-11-13.
What you can do
- Multiple Protocols: SAO (Alternating Offers), Single-Text, Auctions, and custom protocols
- Rich Utility Functions: Linear, nonlinear, constraint-based, probabilistic, dynamic
- Bilateral & Multilateral: Support for 2+ party negotiations
- Concurrent Negotiations: Agents can participate in multiple negotiations simultaneously
Measured star growth
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- +2
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Negotiation Multi-Agent System (A negotiation library designed for situated negotiations within business-like simulations)
AIREADME.md
OriginalNegMAS: Negotiation Multi-Agent System
.. start-badges
.. image:: https://img.shields.io/pypi/pyversions/negmas.svg :target: https://pypi.python.org/pypi/negmas :alt: Python
.. image:: https://img.shields.io/pypi/status/negmas.svg :target: https://pypi.python.org/pypi/negmas :alt: Pypi
.. image:: https://img.shields.io/pypi/l/negmas.svg :target: https://pypi.python.org/pypi/negmas :alt: License
.. image:: https://img.shields.io/pypi/dm/negmas.svg :target: https://pypi.python.org/pypi/negmas :alt: Downloads
.. image:: https://img.shields.io/codacy/grade/1b204fe0a69e41a298a175ea225d7b81.svg :target: https://app.codacy.com/project/yasserfarouk/negmas/dashboard :alt: Code Quality
.. image:: https://img.shields.io/pypi/v/negmas.svg :target: https://pypi.python.org/pypi/negmas :alt: Pypi
.. image:: https://github.com/yasserfarouk/negmas/workflows/CI/badge.svg :target: https://www.github.com/yasserfarouk/negmas :alt: Build Status
.. image:: https://codecov.io/gh/yasserfarouk/negmas/branch/master/graph/badge.svg :target: https://codecov.io/gh/yasserfarouk/negmas :alt: Coverage Status
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/ambv/black :alt: Coding style black
.. image:: https://static.pepy.tech/personalized-badge/negmas?period=total&units=international_system&left_color=black&right_color=blue&left_text=Downloads :target: https://pepy.tech/projects/negmas
.. end-badges
NegMAS is a Python library for developing autonomous negotiation agents embedded in simulation environments. It supports bilateral and multilateral negotiations, multiple negotiation protocols, and complex multi-agent simulations with interconnected negotiations.
Documentation: https://negmas.readthedocs.io/
Installation
.. code-block:: bash
pip install negmas
For additional features:
.. code-block:: bash
# With Genius bridge support (Java-based agents)
pip install negmas[genius]
# With visualization support
pip install negmas[plots]
# All optional dependencies
pip install negmas[all]
Quick Start
Run a simple negotiation in 10 lines:
.. code-block:: python
from negmas import SAOMechanism, TimeBasedConcedingNegotiator, make_issue
from negmas.preferences import LinearAdditiveUtilityFunction as LUFun
# Define what we're negotiating about
issues = [make_issue(name="price", values=100)]
# Create negotiation session (Stacked Alternating Offers)
session = SAOMechanism(issues=issues, n_steps=50)
# Add buyer (prefers low price) and seller (prefers high price)
session.add(
TimeBasedConcedingNegotiator(name="buyer"),
ufun=LUFun.random(issues=issues, reserved_value=0.0),
)
session.add(
TimeBasedConcedingNegotiator(name="seller"),
ufun=LUFun.random(issues=issues, reserved_value=0.0),
)
# Run and get result
result = session.run()
print(f"Agreement: {result.agreement}, Rounds: {result.step}")
Multi-issue negotiation with custom preferences:
.. code-block:: python
from negmas import SAOMechanism, AspirationNegotiator, make_issue
from negmas.preferences import LinearAdditiveUtilityFunction
# Create a 2-issue negotiation domain
issues = [
make_issue(name="price", values=10),
make_issue(name="quantity", values=5),
]
# Define utility functions
buyer_ufun = LinearAdditiveUtilityFunction(
values={
"price": lambda x: 1.0 - x / 10.0, # lower price = better
"quantity": lambda x: x / 5.0, # more quantity = better
},
issues=issues,
)
seller_ufun = LinearAdditiveUtilityFunction(
values={
"price": lambda x: x / 10.0, # higher price = better
"quantity": lambda x: 1.0 - x / 5.0, # less quantity = better
},
issues=issues,
)
# Run negotiation
session = SAOMechanism(issues=issues, n_steps=100)
session.add(AspirationNegotiator(name="buyer"), ufun=buyer_ufun)
session.add(AspirationNegotiator(name="seller"), ufun=seller_ufun)
session.run()
# Visualize
session.plot()
Command Line Interface
NegMAS includes a negotiate CLI for quick experimentation:
.. code-block:: bash
# Run with default negotiators
negotiate -s 50
# Specify negotiators and steps
negotiate -n AspirationNegotiator -n NaiveTitForTatNegotiator -s 100
# Use Python-native Genius agents (no Java required)
negotiate -n GBoulware -n GConceder -s 50
# Use custom BOA components
negotiate -n "boa:offering=GTimeDependentOffering(e=0.2),acceptance=GACNext" -n AspirationNegotiator
# Save results and plot
negotiate -s 100 --save-path ./results
See negotiate --help for all options, or the CLI documentation <https://negmas.readthedocs.io/en/latest/scripts.html>_.
Architecture Overview
NegMAS is built around four core concepts:
.. code-block:: text
┌─────────────────────────────────────────────────────────────────┐
│ WORLD │
│ (Simulation environment where agents interact) │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────────────────┐ │
│ │ Agent │ │ Agent │ ... │ BulletinBoard │ │
│ │ │ │ │ │ (Public info) │ │
│ └────┬────┘ └────┬────┘ └─────────────────────┘ │
│ │ │ │
│ │ creates │ creates │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ MECHANISM │ │
│ │ (Negotiation protocol: SAO, SingleText, Auction, etc.) │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
│ │ │ Negotiator │ │ Negotiator │ │ Negotiator │ │ │
│ │ │ + UFun │ │ + UFun │ │ + UFun │ │ │
│ │ └────────────┘ └────────────┘ └────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Core Components:
Outcome Space (
outcomesmodule)- Issues: Variables being negotiated (price, quantity, delivery date, etc.)
- Outcomes: Specific assignments of values to issues
- Supports discrete, continuous, and categorical issues
Preferences (
preferencesmodule)- UtilityFunction: Maps outcomes to utility values
- Built-in types:
LinearAdditiveUtilityFunction,MappingUtilityFunction,NonLinearAggregationUtilityFunction, and more - Supports probabilistic and dynamic utility functions
Negotiators (
negotiators,saomodules)- Implement negotiation strategies
- Built-in:
AspirationNegotiator,TitForTatNegotiator,NaiveTitForTatNegotiator,BoulwareTBNegotiator, etc. - Easy to create custom negotiators
Mechanisms (
mechanisms,saomodules)- Implement negotiation protocols
SAOMechanism: Stacked Alternating Offers (most common)- Also: Single-text protocols, auction mechanisms, etc.
For Situated Negotiations (World Simulations):
Worlds (
situatedmodule)- Simulate environments where agents negotiate
- Agents can run multiple concurrent negotiations
- Example: Supply chain simulations (SCML)
Controllers (
sao.controllersmodule)- Coordinate multiple negotiators
- Useful when negotiations are interdependent
Key Features
- Multiple Protocols: SAO (Alternating Offers), Single-Text, Auctions, and custom protocols
- Rich Utility Functions: Linear, nonlinear, constraint-based, probabilistic, dynamic
- Bilateral & Multilateral: Support for 2+ party negotiations
- Concurrent Negotiations: Agents can participate in multiple negotiations simultaneously
- World Simulations: Build complex multi-agent simulations with situated negotiations
- Genius Integration: Run Java-based Genius agents via the built-in bridge
- Visualization: Built-in plotting for negotiation analysis
- Extensible: Easy to add new protocols, negotiators, and utility functions
Creating Custom Negotiators
NegMAS offers two approaches to creating custom negotiators:
- Inheritance: Subclass a base negotiator and override methods
- Composition: Combine multiple negotiators using
MetaNegotiator
Inheritance (Traditional Approach)
Subclass a base negotiator and implement the required methods:
.. code-block:: python
from negmas.sao import SAONegotiator, ResponseType
class MyNegotiator(SAONegotiator):
"""A simple negotiator using inheritance."""
def propose(self, state, dest=None):
# Propose a random outcome above reservation value
return self.nmi.random_outcome()
def respond(self, state, source=None):
offer = state.current_offer
# Accept any offer with utility > 0.8
if offer is not None and self.ufun(offer) > 0.8:
return ResponseType.ACCEPT_OFFER
return ResponseType.REJECT_OFFER
**Using the negotiator:**
.. code-block:: python
session = SAOMechanism(issues=issues, n_steps=100)
session.add(MyNegotiator(name="custom"), ufun=my_ufun)
session.add(AspirationNegotiator(name="opponent"), ufun=opponent_ufun)
session.run()
Composition (Ensemble Approach)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use ``SAOAggMetaNegotiator`` to combine multiple negotiators and aggregate their decisions:
.. code-block:: python
from negmas.sao import SAOMechanism, ResponseType
from negmas.sao.negotiators import (
SAOAggMetaNegotiator,
BoulwareTBNegotiator,
NaiveTitForTatNegotiator,
)
class MajorityVoteNegotiator(SAOAggMetaNegotiator):
"""An ensemble negotiator that uses majority voting."""
def aggregate_proposals(self, state, proposals, dest=None):
# Use the proposal from the first negotiator that offers something
for neg, proposal in proposals:
if proposal is not None:
return proposal
return None
def aggregate_responses(self, state, responses, offer, source=None):
# Majority vote: accept if more than half accept
accept_count = sum(1 for _, r in responses if r == ResponseType.ACCEPT_OFFER)
if accept_count > len(responses) / 2:
return ResponseType.ACCEPT_OFFER
return ResponseType.REJECT_OFFER
# Create an ensemble of different strategies
ensemble = MajorityVoteNegotiator(
negotiators=[
BoulwareTBNegotiator(), # Tough strategy
NaiveTitForTatNegotiator(), # Reactive strategy
BoulwareTBNegotiator(), # Another tough vote
],
name="ensemble",
)
# Use in a negotiation
session = SAOMechanism(issues=issues, n_steps=100)
session.add(ensemble, ufun=my_ufun)
session.add(AspirationNegotiator(name="opponent"), ufun=opponent_ufun)
session.run()
The ensemble approach is useful for:
- **Voting strategies**: Combine multiple negotiators via majority/weighted voting
- **Dynamic delegation**: Switch between strategies at runtime
- **A/B testing**: Compare strategies within the same negotiation
Composition (BOA Components)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use ``BOANegotiator`` to build negotiators from reusable components following
the Bidding-Opponent modeling-Acceptance (BOA) pattern:
.. code-block:: python
from negmas.gb.negotiators.modular import BOANegotiator
from negmas.gb.components import (
GSmithFrequencyModel, # Opponent modeling
GACTime, # Acceptance strategy
GTimeDependentOffering, # Offering strategy
)
# Create a BOA negotiator with Genius-style components
negotiator = BOANegotiator(
offering=GTimeDependentOffering(e=0.2), # Boulware-style offering
acceptance=GACTime(t=0.95), # Accept after 95% of time
model=GSmithFrequencyModel(), # Opponent frequency model
name="my_boa_agent",
)
The BOA approach is useful for:
- **Mix-and-match**: Combine different strategies from the Genius library
- **Research**: Easily swap components to compare different strategies
- **Extensibility**: Create custom components that integrate with existing ones
Creating Custom Protocols
-------------------------
.. code-block:: python
from negmas import Mechanism, MechanismStepResult
class MyProtocol(Mechanism):
def __call__(self, state, action=None):
# Implement one round of your protocol
# Return MechanismStepResult with updated state
...
return MechanismStepResult(state=state)
Running World Simulations
-------------------------
For complex scenarios with multiple agents and concurrent negotiations:
.. code-block:: python
from negmas.situated import World, Agent
class MyAgent(Agent):
def step(self):
# Called each simulation step
# Request negotiations, respond to events, etc.
pass
# See SCML package for a complete example
# pip install scml
Citation
--------
If you use NegMAS in your research, please cite:
.. code-block:: bibtex
@inproceedings{mohammad2021negmas,
title={NegMAS: A Platform for Automated Negotiations},
author={Mohammad, Yasser and Nakadai, Shinji and Greenwald, Amy},
booktitle={PRIMA 2020: Principles and Practice of Multi-Agent Systems},
pages={343--351},
year={2021},
publisher={Springer},
doi={10.1007/978-3-030-69322-0_23}
}
**Reference:**
Mohammad, Y., Nakadai, S., Greenwald, A. (2021). NegMAS: A Platform for Automated Negotiations.
In: *PRIMA 2020*. LNCS, vol 12568. Springer. https://doi.org/10.1007/978-3-030-69322-0_23
The NegMAS Ecosystem
--------------------
NegMAS is the core of a broader ecosystem for automated negotiation research:
.. image:: https://raw.githubusercontent.com/yasserfarouk/negmas/main/docs/figs/ecosystem.png
:alt: NegMAS Ecosystem
:align: center
:width: 100%
**Competition Frameworks**
- `anl <https://github.com/autoneg/anl>`_ - Automated Negotiation League (ANAC negotiation track)
- `scml <https://github.com/yasserfarouk/scml>`_ - Supply Chain Management League
**Agent Repositories**
- `anl-agents <https://github.com/autoneg/anl-agents>`_ - ANL competition agents
- `scml-agents <https://github.com/yasserfarouk/scml-agents>`_ - SCML competition agents
**Bridges & Extensions**
- `negmas-geniusweb-bridge <https://github.com/autoneg/negmas-geniusweb-bridge>`_ - Run GeniusWeb agents
- `negmas-llm <https://github.com/autoneg/negmas-llm>`_ - LLM-powered negotiation agents
- `negmas-elicit <https://github.com/autoneg/negmas-elicit>`_ - Preference elicitation during negotiation
- `geniusbridge <https://github.com/yasserfarouk/geniusbridge>`_ - Java Genius bridge
**Visualization & Tools**
- `negmas-app <https://github.com/autoneg/negmas-app>`_ - Applications and interfaces for NegMAS
- `scml-vis <https://github.com/yasserfarouk/scml-vis>`_ - SCML visualization
- `jnegmas <https://github.com/yasserfarouk/jnegmas>`_ - Java interface (not maintained)
**Specialized Tools**
- `negmas-elicit <https://github.com/autoneg/negmas-elicit>`_ - Preference Elicitation during Negotiation Methods
More Resources
--------------
- **Tutorials**: https://negmas.readthedocs.io/en/latest/tutorials.html
- **API Reference**: https://negmas.readthedocs.io/en/latest/api.html
- **YouTube Playlist**: https://www.youtube.com/playlist?list=PLqvs51K2Mb8IJe5Yz5jmYrRAwvIpGU2nF
- **Publications**: https://negmas.readthedocs.io/en/latest/publications.html
Papers Using NegMAS
-------------------
Selected papers (see `full list <https://negmas.readthedocs.io/en/latest/publications.html>`_):
**Core NegMAS Research** (by the NegMAS authors)
- Mohammad, Y. (2025). `Tackling the Protocol Problem in Automated Negotiation <https://www.ifaamas.org/Proceedings/aamas2025/pdfs/p246.pdf>`_. AAMAS. *Cited by 1*
- Florijn et al. (2025). `A Survey on One-to-Many Negotiation <https://www.ijcai.org/proceedings/2025/928>`_. IJCAI. *Cited by 1*
- Mohammad, Y. et al. (2024). `Automated Negotiation in Supply Chains: A Generalist Environment for RL/MARL <https://doi.org/10.1007/978-981-96-1072-1_1>`_. PRIMA. *Cited by 1*
- Mohammad, Y. (2023). `Generalized Bargaining Protocols <https://doi.org/10.1007/978-981-99-8391-9_27>`_. AI 2023. *Cited by 3*
- Mohammad, Y. (2023). `Optimal Time-based Strategy for Automated Negotiation <https://doi.org/10.1007/s10489-022-03893-x>`_. Applied Intelligence. *Cited by 9*
- Mohammad, Y. (2023). `Evaluating Automated Negotiations <https://doi.org/10.1109/WI-IAT59888.2023.00015>`_. IEEE WI-IAT. *Cited by 2*
- Mohammad, Y. (2021). `Concurrent Local Negotiations with a Global Utility Function <https://doi.org/10.1007/s10458-020-09490-7>`_. AAMAS Journal. *Cited by 14*
- Mohammad, Y. (2020). `Optimal Deterministic Time-based Policy in Automated Negotiation <https://doi.org/10.1007/978-3-030-69322-0_5>`_. PRIMA. *Cited by 4*
- Mohammad, Y., Nakadai, S. (2019). `Optimal Value of Information Based Elicitation <https://dl.acm.org/doi/10.5555/3306127.3331698>`_. AAMAS.
- Mohammad, Y., Nakadai, S. (2018). `FastVOI: Efficient Utility Elicitation <https://doi.org/10.1007/978-3-030-03098-8_34>`_. PRIMA.
- Mohammad, Y. et al. (2019). `Supply Chain Management World <https://doi.org/10.1007/978-3-030-33792-6_10>`_. PRIMA. *Cited by 38*
**Competition & Benchmarks**
- Aydoğan et al. (2025). `ANAC 2024 Challenges and Results <https://www.ifaamas.org/Proceedings/aamas2025/pdfs/p2640.pdf>`_. AAMAS. *Cited by 2*
- Aydoğan et al. (2020). `Challenges and Main Results of ANAC 2019 <https://doi.org/10.1007/978-3-030-66412-1_23>`_. EUMAS/AT. *Cited by 51*
**Negotiation Strategies**
- Sengupta et al. (2021). `RL-Based Negotiating Agent Framework <https://arxiv.org/abs/2102.03588>`_. IJCAI *Cited by 48*
- Higa et al. (2023). `Reward-based Negotiating Agent Strategies <https://ojs.aaai.org/index.php/AAAI/article/view/26831>`_. AAAI. *Cited by 16*
**Applications**
- Inotsume et al. (2020). `Path Negotiation for Multirobot Vehicles <https://doi.org/10.1109/IROS45743.2020.9340819>`_. IROS. *Cited by 17*
*Last updated: February 2026*
Contributing
------------
Contributions are welcome! Please see the `contributing guide <https://negmas.readthedocs.io/en/latest/contributing.html>`_.
License
-------
NegMAS is released under the BSD 3-Clause License.
AI Assistance Disclosure
------------------------
This project uses AI assistance for specific, limited tasks while remaining predominantly human-developed:
- **Publications list**: AI assisted in compiling and formatting the publications list
- **Documentation polishing**: AI assisted in proofreading and improving documentation clarity
- **gb.components.genius module**: AI assisted in reimplementing Genius BOA components in NegMAS
- **Registry feature**: AI assisted in developing the negotiator/mechanism registry system
- **Some tests**: AI assisted in writing tests, particularly for new features like the registry
- **tournaments.analysis module**: AI assisted in implementing the post-tournament game-theoretic and
statistical analysis package (EGTA-based evaluation, Sequential Elimination Ranking, replicator
dynamics, and pairwise significance/normality testing)
All AI-assisted contributions are reviewed and approved by human maintainers. The core architecture,
algorithms, and research direction of NegMAS are human-driven and will remain so.
Acknowledgements
----------------
NegMAS was developed at the NEC-AIST collaborative laboratory. It uses scenarios from
ANAC 2010-2018 competitions obtained from the `Genius Platform <http://ii.tudelft.nl/genius>`_.