# yasserfarouk/negmas architecture

> Architecture diagram of the GitHub repository yasserfarouk/negmas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yasserfarouk/negmas
- Repository: https://github.com/yasserfarouk/negmas

## Overview

##### Project type and purpose
- This is an open-source Python library (negmas) for building and running autonomous negotiation agents and simulations (“situated simultaneous negotiations”).
- It offers a public API, internal core modules, sample negotiators, negotiation protocols, utility‐function support, and a world simulation framework.

##### File structure
- Top‐level directories:
- src/negmas: the library’s Python package, split into many subpackages (common, events, mechanisms, negotiators, preferences, outcomes, sao, situated, etc.).
- docs/, notebooks/: user documentation and interactive examples.
- config/, etc/: sample configuration files and auxiliary scripts.
- tests/: unit and integration tests organized by module.
- scripts under src/negmas/scripts and run_*.sh: CLI entry points.
- Key configuration/deployment files: pyproject.toml, tox.ini, GitHub workflows under .github, README.rst, setup-related files.
- External dependency: a JAR file (“jnegmas”) under src/negmas/external for Genius integration.

##### README for additional insights
- Public API vs. internal implementation is deliberately decoupled.
- Supports multiple concurrent negotiations (concurrent subpackage) and inter-session controllers.
- Core extensibility points:
– Negotiators (negmas.negotiators and negmas.sao.negotiators)
– Mechanisms (negmas and negmas.sao modules)
– Worlds (negmas.situated)
– Utility functions (negmas.preferences)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User Code\n(scripts, notebooks, CLI)"]:::external

    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        API_Init["__init__.py"]:::public
        API_App["app.py"]:::public
        API_Negotiate["negotiate.py"]:::public
        CLI_Wrapper["run_with_timeout.sh"]:::public
    end

    %% Configuration Loader
    Config["Configuration Loader\n(config.py)"]:::core

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Mechanisms["Mechanisms\n(mechanisms.py,\n gb/base.py,\n gb/tau.py,\n gb/tauserial.py,\n sao/mechanism.py)"]:::core
        Negotiators["Negotiator Frameworks\n(negotiators/, sao/negotiators/, gb/negotiators/)"]:::extension
        Protocols["Protocols & Controllers\n(protocols.py,\n concurrent/chain.py,\n sao/controllers.py)"]:::core
        Preferences["Utility Functions\n(preferences/)"]:::extension
        Outcomes["Outcome-space\n(outcomes/)"]:::extension
        Events["Events & State\n(events.py,\n checkpoints.py)"]:::core
        World["Situated World Simulation\n(situated/)"]:::extension
        Serialization["Persistence/Serialization\n(serialization.py,\n helpers/inout.py)"]:::core
    end

    %% External Bridges
    subgraph "External Integration"
        direction TB
        Jnegmas["jnegmas-1.0-SNAPSHOT-all.jar"]:::external
        Genius["Genius Bridge\n(genius/)"]:::external
    end

    %% Common Utilities
    Common["Common Utilities\n(common.py,\n helpers/)"]:::external

    %% Connections
    User -->|calls| API_Init
    User -->|runs| API_App
    User -->|runs| API_Negotiate
    User -->|invokes| CLI_Wrapper

    API_Init -->|loads| Config
    API_App --> Config
    API_Negotiate --> Config

    Config -->|configures| Mechanisms
    Config -->|configures| World

    API_Init -->|calls| Mechanisms
    API_Init -->|calls| Negotiators
    API_Init -->|calls| Protocols
    API_Init -->|calls| Preferences
    API_Init -->|calls| Outcomes
    API_Init -->|calls| World

    Mechanisms -->|coordinates| Negotiators
    Negotiators -->|uses| Preferences
    Negotiators -->|uses| Outcomes
    Mechanisms -->|publishes| Events
    Protocols -->|orchestrates| Mechanisms
    Protocols -->|observes| Events

    World -->|wraps| Mechanisms
    World -->|monitors| Events

    Mechanisms -->|invokes| Jnegmas
    Negotiators -->|invokes| Genius

    Mechanisms -->|serializes| Serialization
    World -->|serializes| Serialization

    Mechanisms -->|utilizes| Common
    Negotiators -->|utilizes| Common
    Preferences -->|utilizes| Common
    Outcomes -->|utilizes| Common
    Events -->|utilizes| Common

    %% Click Events
    click API_Init "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/__init__.py"
    click API_App "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/scripts/app.py"
    click API_Negotiate "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/scripts/negotiate.py"
    click CLI_Wrapper "https://github.com/yasserfarouk/negmas/blob/master/run_with_timeout.sh"
    click Config "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/config.py"
    click Mechanisms "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/mechanisms.py"
    click Mechanisms "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/sao/mechanism.py"
    click Mechanisms "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/mechanisms/base.py"
    click Mechanisms "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/mechanisms/tau.py"
    click Mechanisms "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/mechanisms/tauserial.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/negotiators/common.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/negotiators/negotiator.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/negotiators/simple.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/tree/master/src/negmas/negotiators/components/"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/sao/negotiators/base.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/sao/negotiators/cab.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/sao/negotiators/hybrid.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/sao/negotiators/controlled.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/tree/master/src/negmas/sao/negotiators/modular/"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/negotiators/base.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/negotiators/cab.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/negotiators/hybrid.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/tree/master/src/negmas/gb/negotiators/modular/"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/negotiators/randneg.py"
    click Negotiators "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/gb/negotiators/titfortat.py"
    click Protocols "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/protocols.py"
    click Protocols "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/concurrent/chain.py"
    click Protocols "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/sao/controllers.py"
    click Preferences "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/preferences/base.py"
    click Preferences "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/preferences/complex.py"
    click Preferences "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/preferences/protocols.py"
    click Outcomes "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/outcomes/base_issue.py"
    click Outcomes "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/outcomes/categorical_issue.py"
    click Outcomes "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/outcomes/outcome_space.py"
    click Outcomes "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/outcomes/protocols.py"
    click Events "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/events.py"
    click Events "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/checkpoints.py"
    click World "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/situated/world.py"
    click World "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/situated/simple.py"
    click World "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/situated/agent.py"
    click World "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/situated/mechanismfactory.py"
    click World "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/situated/save.py"
    click World "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/situated/monitors.py"
    click Jnegmas "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/external/jnegmas-1.0-SNAPSHOT-all.jar"
    click Genius "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/genius/bridge.py"
    click Genius "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/genius/gnegotiators.py"
    click Genius "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/genius/negotiator.py"
    click Genius "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/genius/common.py"
    click Genius "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/genius/ginfo.py"
    click Serialization "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/serialization.py"
    click Serialization "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/helpers/inout.py"
    click Common "https://github.com/yasserfarouk/negmas/blob/master/src/negmas/common.py"
    click Common "https://github.com/yasserfarouk/negmas/tree/master/src/negmas/helpers/"
    
    %% Styles
    classDef public fill:#cce5ff,stroke:#666,stroke-width:1px
    classDef core fill:#d4edda,stroke:#666,stroke-width:1px
    classDef extension fill:#fff3cd,stroke:#666,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#666,stroke-width:1px
```
