docs: fix broken examples and update publications

- Fix API breaking changes in all documentation examples:
  * Replace SAOMetaNegotiator with SAOAggMetaNegotiator for aggregation
  * Update LinearAdditiveUtilityFunction.random() to use keyword arg
  * Fix GBNegotiator/BOANegotiator BOA components example
- Update publications list with 2024-2025 papers (12 new entries)
- Add caveat note for ensemble sub-negotiator behavior
- Update AGENTS.md with documentation testing requirements
- All examples verified working with test files in coding_agents/

Author: yasserfarouk

AGENTS.md

@@ -19,6 +19,37 @@
 3. **WAIT FOR EXPLICIT "PUSH" COMMAND**
 4. Only then run `git push`
 
+## ⚠️ CRITICAL: DOCUMENTATION EXAMPLES MUST ALWAYS WORK ⚠️
+
+**ALL EXAMPLES IN README.rst AND docs/ MUST BE TESTED AND WORKING AT ALL TIMES**
+
+**BEFORE ANY COMMIT THAT CHANGES APIs OR EXAMPLES:**
+1. Test EVERY code example in `README.rst`
+2. Test EVERY code example in `docs/*.rst`
+3. All examples must run without errors
+4. Create/update test files in `coding_agents/` directory to verify examples
+
+**TEST PROCEDURE:**
+```bash
+# Test README examples
+python coding_agents/test_readme_examples.py
+
+# Test documentation examples
+python coding_agents/test_doc_examples.py
+```
+
+**WHEN UPDATING APIs:**
+1. Search for ALL usages of the old API in README.rst and docs/
+2. Update ALL examples to use the new API
+3. Test ALL updated examples
+4. Never commit broken examples
+
+**COMMON PATTERNS TO CHECK:**
+- `LinearAdditiveUtilityFunction.random()` - must use `issues=` or `outcome_space=` keyword arg
+- `SAOMetaNegotiator` with aggregation methods - should be `SAOAggMetaNegotiator`
+- Any deprecated or changed class names
+- Any deprecated or changed method signatures
+
 ## Build/Test Commands
 ```bash
 pytest                                    # Run all tests
@@ -45,6 +76,7 @@ pre-commit run --all-files                # Run all pre-commit hooks
 - **Errors**: Raise `ValueError`/`TypeError` with descriptive messages; use `negmas.warnings` for deprecations
 - **Source location**: Main code in `src/negmas/`, tests in `tests/`
 - **Docstrings**: ALWAYS test every docstring example you add using `python -c "..."` or `pytest --doctest-modules` before committing
+- **Documentation examples**: ALWAYS test README.rst and docs/*.rst examples using test files in `coding_agents/` before committing
 
 ## Agent Sandbox
 - **File Storage**: All files created for documentation, internal testing, or any other purpose must be placed in the `coding_agents/` directory. This is to avoid polluting the root directory.

README.rst

@@ -89,11 +89,11 @@ Quick Start
     # Add buyer (prefers low price) and seller (prefers high price)
     session.add(
         TimeBasedConcedingNegotiator(name="buyer"),
-        ufun=LUFun.random(issues, reserved_value=0.0),
+        ufun=LUFun.random(issues=issues, reserved_value=0.0),
     )
     session.add(
         TimeBasedConcedingNegotiator(name="seller"),
-        ufun=LUFun.random(issues, reserved_value=0.0),
+        ufun=LUFun.random(issues=issues, reserved_value=0.0),
     )
 
     # Run and get result
@@ -280,19 +280,19 @@ Subclass a base negotiator and implement the required methods:
 Composition (Ensemble Approach)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use ``SAOMetaNegotiator`` to combine multiple negotiators and aggregate their decisions:
+Use ``SAOAggMetaNegotiator`` to combine multiple negotiators and aggregate their decisions:
 
 .. code-block:: python
 
     from negmas.sao import SAOMechanism, ResponseType
     from negmas.sao.negotiators import (
-        SAOMetaNegotiator,
+        SAOAggMetaNegotiator,
         BoulwareTBNegotiator,
         NaiveTitForTatNegotiator,
     )
 
 
-    class MajorityVoteNegotiator(SAOMetaNegotiator):
+    class MajorityVoteNegotiator(SAOAggMetaNegotiator):
         """An ensemble negotiator that uses majority voting."""
 
         def aggregate_proposals(self, state, proposals, dest=None):
@@ -471,6 +471,7 @@ Selected papers (see `full list <https://negmas.readthedocs.io/en/latest/publica
 **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*
@@ -483,6 +484,7 @@ Selected papers (see `full list <https://negmas.readthedocs.io/en/latest/publica
 
 **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**

docs/modules/genius.rst

@@ -61,8 +61,8 @@ Usage Example
    issues = [make_issue(10, "price"), make_issue(5, "quantity")]
 
    # Create utility functions for each negotiator
-   ufun1 = LinearAdditiveUtilityFunction.random(issues, reserved_value=0.0)
-   ufun2 = LinearAdditiveUtilityFunction.random(issues, reserved_value=0.0)
+   ufun1 = LinearAdditiveUtilityFunction.random(issues=issues, reserved_value=0.0)
+   ufun2 = LinearAdditiveUtilityFunction.random(issues=issues, reserved_value=0.0)
 
    # Create negotiators
    n1 = GHardHeaded(name="buyer", ufun=ufun1)
@@ -240,27 +240,25 @@ Example using a Bayesian opponent model with a custom negotiator:
 
 .. code-block:: python
 
-   from negmas.gb import GBNegotiator
-   from negmas.gb.components.genius import (
-       GBayesianModel,
+   from negmas.gb.negotiators.modular import BOANegotiator
+   from negmas.gb.components import (
        GTimeDependentOffering,
-       GACNext,
+       GACTime,
    )
    from negmas.sao import SAOMechanism
    from negmas.preferences import LinearAdditiveUtilityFunction
    from negmas.outcomes import make_issue
 
    # Create scenario
    issues = [make_issue(10, "price"), make_issue(5, "quantity")]
-   ufun = LinearAdditiveUtilityFunction.random(issues, reserved_value=0.0)
+   ufun = LinearAdditiveUtilityFunction.random(issues=issues, reserved_value=0.0)
 
-   # Create negotiator with Bayesian opponent modeling
-   negotiator = GBNegotiator(
-       name="bayesian_agent",
+   # Create negotiator with BOA components
+   negotiator = BOANegotiator(
+       name="boa_agent",
        ufun=ufun,
        offering=GTimeDependentOffering(e=0.5),
-       acceptance=GACNext(),
-       model=GBayesianModel(n_hypotheses=20, rationality=5.0),
+       acceptance=GACTime(t=0.95),
    )
 
 The ``GBayesianModel`` maintains multiple hypotheses about opponent preferences and

docs/negotiation_mechanisms.rst

@@ -44,8 +44,8 @@ turns proposing and responding to offers.
     mechanism = SAOMechanism(issues=issues, n_steps=100)
 
     # Add negotiators
-    mechanism.add(AspirationNegotiator(name="buyer"), ufun=U.random(issues))
-    mechanism.add(AspirationNegotiator(name="seller"), ufun=U.random(issues))
+    mechanism.add(AspirationNegotiator(name="buyer"), ufun=U.random(issues=issues))
+    mechanism.add(AspirationNegotiator(name="seller"), ufun=U.random(issues=issues))
 
     # Run negotiation
     mechanism.run()

docs/negotiators.rst

@@ -871,8 +871,8 @@ Using Native Negotiators
 
    # Run negotiation
    mechanism = SAOMechanism(issues=issues, n_steps=100)
-   mechanism.add(negotiator1, ufun=U.random(issues))
-   mechanism.add(negotiator2, ufun=U.random(issues))
+   mechanism.add(negotiator1, ufun=U.random(issues=issues))
+   mechanism.add(negotiator2, ufun=U.random(issues=issues))
    mechanism.run()
 
 Using Python-Native Genius Negotiators (Recommended)
@@ -896,8 +896,8 @@ These negotiators don't require Java or the Genius bridge.
 
    # Run negotiation
    mechanism = SAOMechanism(issues=issues, n_steps=100)
-   mechanism.add(negotiator1, ufun=U.random(issues))
-   mechanism.add(negotiator2, ufun=U.random(issues))
+   mechanism.add(negotiator1, ufun=U.random(issues=issues))
+   mechanism.add(negotiator2, ufun=U.random(issues=issues))
    mechanism.run()
 
 Using Genius Bridge Negotiators
@@ -930,7 +930,7 @@ Creating Custom Negotiators
 NegMAS offers two approaches to creating custom negotiators:
 
 1. **Inheritance**: Subclass a base negotiator and override methods
-2. **Composition**: Combine multiple negotiators using ``SAOMetaNegotiator``
+2. **Composition**: Combine multiple negotiators using ``SAOAggMetaNegotiator``
 
 Inheritance (Traditional Approach)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -970,14 +970,14 @@ Subclass a base negotiator and implement the required methods:
 Composition (Ensemble Approach)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use ``SAOMetaNegotiator`` to combine multiple negotiators and aggregate their decisions.
+Use ``SAOAggMetaNegotiator`` to combine multiple negotiators and aggregate their decisions.
 This is useful for ensemble strategies, voting mechanisms, or dynamic strategy switching.
 
 .. code-block:: python
 
    from negmas.sao import SAOMechanism, ResponseType
    from negmas.sao.negotiators import (
-       SAOMetaNegotiator,
+       SAOAggMetaNegotiator,
        BoulwareTBNegotiator,
        NaiveTitForTatNegotiator,
        AspirationNegotiator,
@@ -986,7 +986,7 @@ This is useful for ensemble strategies, voting mechanisms, or dynamic strategy s
    from negmas.outcomes import make_issue, make_os
 
 
-   class MajorityVoteNegotiator(SAOMetaNegotiator):
+   class MajorityVoteNegotiator(SAOAggMetaNegotiator):
        """An ensemble negotiator that uses majority voting."""
 
        def aggregate_proposals(self, state, proposals, dest=None):
@@ -1032,6 +1032,14 @@ The ensemble approach is useful for:
 - **Dynamic delegation**: Switch between strategies at runtime
 - **A/B testing**: Compare strategies within the same negotiation
 
+.. note::
+   **Important Consideration**: Sub-negotiators within an ensemble may behave differently
+   than they would in isolation. Their recommended offers and decisions are not guaranteed
+   to be executed in the actual negotiation, which may break implicit assumptions they make
+   about the negotiation flow. For example, a negotiator that expects its offers to be sent
+   in sequence may not work as intended if the ensemble aggregator selects offers from
+   different sub-negotiators.
+
 .. note::
    ``GBMetaNegotiator`` is also available for GB (General Bargaining) protocols
    with additional callbacks for partner events.

docs/publications.rst

@@ -5,8 +5,12 @@ This page lists papers that cite, use, or mention NegMAS and its ecosystem (incl
 
 .. note::
 
-    This list is updated periodically. If you have published a paper using NegMAS that is not listed here,
-    please `open an issue <https://github.com/yasserfarouk/negmas/issues>`_ or submit a pull request.
+    This list is updated periodically using LLMs by searching academic databases.
+    While we strive for accuracy, the automated process may occasionally miss papers or include
+    incorrect information. Please **double check** these citations before reusing them.
+    If you have published a paper using NegMAS that is not listed here,
+    or if you notice any inaccuracies, please `open an issue <https://github.com/yasserfarouk/negmas/issues>`_
+    or submit a pull request.
 
     *Last updated: February 2026*
 
@@ -88,6 +92,10 @@ Papers presenting novel negotiation strategies using NegMAS:
   `Predicting the Outcome of Ongoing Automated Negotiations <https://doi.org/10.1007/978-981-96-1072-1_7>`_.
   In: *PRIMA 2024*. LNCS. Springer.
 
+- 清水拓夢, 藤田桂英 (2024).
+  `サプライチェーンにおける合意可能価格予測を考慮した自動交渉戦略 <https://ipsj.ixsq.nii.ac.jp/ej/?action=pages_view_main&active_action=repository_view_main_item_detail&item_id=235829&item_no=1&page_id=13&block_id=8>`_.
+  情報処理学会論文誌 (IPSJ Journal). *Cited by 1*
+
 - Aguilera-Luzon, D., de Jonge, D., Larrosa, J. (2025).
   `MiCRO for Multilateral Negotiations <https://doi.org/10.1007/978-981-96-1072-1_6>`_.
   In: *PRIMA 2024*. LNCS. Springer.
@@ -178,6 +186,10 @@ Papers on negotiation protocols and theoretical aspects:
   `A Survey on One-to-Many Negotiation: A Taxonomy of Interdependency <https://www.ijcai.org/proceedings/2025/928>`_.
   In: *Proceedings of IJCAI 2025*. *Cited by 1*
 
+- de Jonge, D. (2025).
+  `BINGO: An Algorithm for Automated Negotiations with Hidden Reservation Values <https://iiia.csic.es/~davedejonge/homepage/papers/bingo.pdf>`_.
+  Technical Report.
+
 - de Jonge, D. (2025).
   `Introduction to Automated Negotiation <https://arxiv.org/abs/2511.08659>`_.
   arXiv:2511.08659.
@@ -230,17 +242,13 @@ Papers describing other platforms that use or compare with NegMAS:
   `NegoSim: A Modular and Extendable Automated Negotiation Simulation Platform Considering EUBOA <https://doi.org/10.3390/app13179396>`_.
   *Applied Sciences*. *Cited by 7*
 
-- Keskin, M.O., Buzcu, B., Koçyiğit, B., et al. (2024).
-  `NEGOTIATOR: A Comprehensive Framework for Human-Agent Negotiation <https://doi.org/10.1145/3652988.3673933>`_.
-  In: *Proceedings of AAMAS 2024*. *Cited by 2*
-
 - Doğru, A., Keskin, M.O., Aydoğan, R. (2025).
   `Taking into Account Opponent's Arguments in Human-Agent Negotiations <https://doi.org/10.1145/3701460>`_.
   *ACM Transactions on Interactive Intelligent Systems*. *Cited by 3*
 
-- de Jonge, D. (2025).
-  `BINGO: An Algorithm for Automated Negotiations with Hidden Reservation Values <https://iiia.csic.es/~davedejonge/homepage/papers/bingo.pdf>`_.
-  Technical Report.
+- Keskin, M.O., Buzcu, B., Koçyiğit, B., et al. (2024).
+  `NEGOTIATOR: A Comprehensive Framework for Human-Agent Negotiation <https://doi.org/10.1145/3652988.3673933>`_.
+  In: *Proceedings of AAMAS 2024*. *Cited by 2*
 
 
 Applications