Imported from yasserfarouk/negmas (AGENTS.md). Install upstream with npx skills add yasserfarouk/negmas. Copyright stays with the author.

Agent Guidelines for negmas

⚠️ CRITICAL: GIT PUSH POLICY ⚠️

NEVER NEVER NEVER NEVER PUSH WITHOUT EXPLICIT INSTRUCTION

ABSOLUTELY NO EXCEPTIONS. NEVER PUSH TO GITHUB WITHOUT THE USER EXPLICITLY SAYING "PUSH" OR GIVING A DIRECT COMMAND TO PUSH.

DO NOT PUSH EVEN IF:

• All tests pass locally
• All tests pass on CI
• The changes look good
• You think it's ready
• You want to check CI

ALWAYS:

1. Run tests locally
2. Show results to user
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:

# 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

pytest                                    # Run all tests
pytest tests/core/test_sao.py             # Run single test file
pytest tests/core/test_sao.py::test_name  # Run single test function
pytest -k "pattern"                       # Run tests matching pattern
NEGMAS_FASTRUN=True pytest                # Fast test mode

Lint/Format Commands

ruff check --fix --unsafe-fixes           # Lint and auto-fix
ruff format                               # Format code
pre-commit run --all-files                # Run all pre-commit hooks

Code Style

• Line length: 88 chars, indent: 4 spaces, quotes: double
• Python target: 3.11+ (use | for unions: int | None)
• Imports: from __future__ import annotations first, then stdlib, third-party, local
• Naming: PascalCase for classes, snake_case for functions/variables, _prefix for private
• Types: Use type hints everywhere; use TYPE_CHECKING block for type-only imports
• Classes: Use @define from attrs for data classes; every module exports via __all__
• 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.

Git Workflow

• Do not push: Never push commits to origin without explicit user approval. Commit changes locally, but wait for the user to say "push" or similar before running git push.
• Always add tests: Every new feature must have corresponding tests. Add tests to tests/core/ for core functionality.
• Test naming: Use test_<feature_name> naming convention for test functions.
• Run tests: Always run relevant tests after implementing a feature to verify it works.

Publications List Maintenance

Task: Periodically update the publications list (approximately every 2 weeks).

Files to update:

• docs/publications.rst - Full comprehensive list with all details
• README.rst - Condensed "Papers Using NegMAS" section

Search queries to use (Google Scholar):

• "negmas" negotiation
• "SCML" "supply chain" negotiation agent
• "supply chain management league" ANAC
• "automated negotiating agents competition" SCML

Entry format for publications.rst:

- Author1, A., Author2, B. (Year).
  `Paper Title <URL>`_.
  In: *Venue Name*. Publisher. *Cited by N*

Process:

1. Search using the queries above
2. Filter for papers that actually use/cite NegMAS or SCML
3. Add new entries to the appropriate category in docs/publications.rst
4. For significant papers (high citations or major venues), also add to README.rst
5. Update the "Last updated" date in publications.rst
6. Verify the documentation builds: cd docs && make html

Ecosystem Maintenance

Task: Periodically review and update the NegMAS ecosystem documentation (approximately every 2 weeks).

Files to update:

• docs/overview.rst - Ecosystem section in main documentation
• README.rst - Ecosystem section in project README

Repositories to check (all under github.com/yasserfarouk/):

Process:

1. Check each repository for recent updates, new releases, or status changes
2. Look for new repositories in the yasserfarouk GitHub account related to NegMAS
3. Verify all repository links are still valid
4. Update descriptions if repository purposes have changed
5. Add any new ecosystem projects to the appropriate category
6. Remove or mark as deprecated any archived/abandoned projects
7. Ensure both docs/overview.rst and README.rst are in sync

Release Process:

I do not use Travis CLI, I use Github Actions.

You must do the following steps for doing a release:

1. confirm the tests pass locally with the genius bridge running.
2. confirm that all commits since the last release are included in HISTORY.rst (minor ones like chores may be ignored).
3. make sure the docs build successfully.
4. commit everything and push.
5. include any security prs.
6. ASK ME AND CONRIRM the new version number. Give me the latest version on pypi and the version currently in pyproject.toml and suggest the new version.
7. tag with the new version number.
8. monitor Github actions until all actions pass (NOTE: SlowCI takes hours, no need to wait for it).
9. push with tags and monitor again.
10. after pypi is updated from github actions confim the version.
11. make a release on github which includes the changes for this release from HISTORY.rst.

Known issues to fix later

Found while integrating the Genius frequency opponent models into an RL negotiator (negmas-rl's RLBOA, 2026-08-28).

1. (fixed) The Genius opponent models never published themselves. Handled in GeniusOpponentModel.on_negotiation_start, which now calls _update_private_info() for all five at once. Remaining wart, not worth churn on its own: the UFunModel family (gb/components/models/ufun.py) still publishes from on_preferences_changed, which has nothing to do with opponent modelling and works only because negmas fires it before on_negotiation_start. Move those to the same hook next time that file is touched.

2. The Genius frequency models learn only through on_partner_proposal. Unlike FrequencyLinearUFunModel, which also implements before_responding, they have no second route, so a negotiator that never receives that callback gets a model that silently never updates.

   Left as one route on purpose. Adding before_responding would give any negotiator receiving both callbacks two learning paths and double-count every offer, which for a frequency model directly corrupts the weights it infers. The case that prompted this -- negmas-rl's training environment -- turned out to be the environment's own gap: it drove after_learner_actions on its codecs but never after_partner_action, and was fixed there.