# zou-group/sirius architecture

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

- Interactive diagram: https://gitdiagram.com/zou-group/sirius
- Repository: https://github.com/zou-group/sirius

## Overview

##### Project type and purpose
- From the file tree and README, this is an open-source research tool (“SiriuS”) implementing a self-improving multi-agent negotiation environment.
- It provides:
- A “NegotiationArena” core package for game mechanics and engine logic
- Plug-and-play game scenarios (ultimatum, buy-sell, trading, simple)
- Agent implementations (ChatGPT, Claude, LLaMA2, custom behaviors)
- Runner and entry-point scripts to launch matches and experiments
- Utilities for logging, parsing, prompt generation, and fine-tuning

##### File structure
Top-level:
- Competitive/NegotiationArena: the core Python package
– games/: per-scenario game logic and prompt definitions
– negotiationarena/: engine, agent interfaces, game objects, utilities
– runner/: experiment scripts for different setups
– buysell_main.py, trading_main.py, ultimatum_main.py: CLI entry points
- agent.py & fine_tune.py: top-level scripts for custom agents and model fine-tuning
- Problem_solving/: possibly separate experiments or examples
- Configuration: .gitignore, LICENSE

##### README for additional insights
– Title and arXiv link reveal academic research focus on “bootstrapped reasoning” in multi-agent systems.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry-Point / CLI Layer
    subgraph "Entry-Point / CLI Layer"
        buysell["buysell_main.py"]:::entry
        trading["trading_main.py"]:::entry
        ultimatum["ultimatum_main.py"]:::entry
        agent_main["agent.py"]:::entry
        fine_tune_main["fine_tune.py"]:::entry
    end

    %% Runner / Experiment Orchestrator
    subgraph "Runner / Experiment Orchestrator"
        one_shot["one_shot_ultimatum.py"]:::runner
        simple_runner["simple_game.py"]:::runner
    end

    %% Core Engine
    subgraph "NegotiationArena Core" 
        alt_game["alternating_game.py"]:::core
        parser["parser.py"]:::core
        logging_mod["logging.py"]:::core
        utils["utils.py"]:::core
        constants["constants.py"]:::core
    end

    %% Game Scenarios
    subgraph "Game Scenarios"
        subgraph "Buy–Sell Scenario"
            buy_game["game.py"]:::scenario
            buy_prompt["prompt.py"]:::scenario
        end
        subgraph "Simple Scenario"
            simple_game["game.py"]:::scenario
            simple_prompt["prompt.py"]:::scenario
        end
        subgraph "Trading Scenario"
            trade_game["game.py"]:::scenario
            trade_interface["interface.py"]:::scenario
            trade_prompt["prompt.py"]:::scenario
        end
        subgraph "Ultimatum Scenario"
            ult_game["game.py"]:::scenario
            ult_interface["interface.py"]:::scenario
            ult_prompt["prompt.py"]:::scenario
        end
    end

    %% Game Objects
    subgraph "Game Objects"
        obj_game["game.py"]:::objects
        obj_goal["goal.py"]:::objects
        obj_resource["resource.py"]:::objects
        obj_trade["trade.py"]:::objects
        obj_valuation["valuation.py"]:::objects
    end

    %% Agent Layer
    subgraph "Agent Layer"
        agent_msg["agent_message.py"]:::agent
        agent_behav["agent_behaviours.py"]:::agent
        agent_base["agents.py"]:::agent
        agent_chat["chatgpt.py"]:::agent
        agent_claude["claude.py"]:::agent
        agent_llama2["llama2.py"]:::agent
    end

    %% External Services
    subgraph "External Services"
        openai["OpenAI API"]:::external
        anthropic["Anthropic API"]:::external
        local_llama["Local LLaMA2"]:::external
    end

    %% Relationships
    buysell -->|launches| one_shot
    trading -->|launches| simple_runner
    ultimatum -->|launches| one_shot
    agent_main -->|initializes| one_shot
    fine_tune_main -->|fine-tunes| agent_llama2

    one_shot -->|orchestrates| alt_game
    simple_runner -->|orchestrates| alt_game

    alt_game -->|parses input| parser
    alt_game -->|records events| logging_mod
    alt_game -->|uses helpers| utils
    alt_game -->|reads constants| constants

    alt_game -->|calls| buy_game
    alt_game -->|calls| simple_game
    alt_game -->|calls| trade_game
    alt_game -->|calls| ult_game

    alt_game -->|instantiates| obj_game
    alt_game -->|updates| obj_goal
    alt_game -->|updates| obj_resource
    alt_game -->|updates| obj_trade
    alt_game -->|updates| obj_valuation

    alt_game -->|sends message| agent_msg
    agent_msg -->|routes to| agent_behav
    agent_behav -->|uses| agent_base
    agent_behav -->|wraps| agent_chat
    agent_behav -->|wraps| agent_claude
    agent_behav -->|wraps| agent_llama2

    agent_chat -->|API call| openai
    agent_claude -->|API call| anthropic
    agent_llama2 -->|model call| local_llama

    %% Click Events
    click buysell "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/buysell_main.py"
    click trading "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/trading_main.py"
    click ultimatum "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/ultimatum_main.py"
    click agent_main "https://github.com/zou-group/sirius/blob/main/Competitive/agent.py"
    click fine_tune_main "https://github.com/zou-group/sirius/blob/main/Competitive/fine_tune.py"
    click one_shot "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/runner/one_shot_ultimatum.py"
    click simple_runner "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/runner/simple_game.py"
    click alt_game "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/alternating_game.py"
    click parser "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/parser.py"
    click logging_mod "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/logging.py"
    click utils "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/utils.py"
    click constants "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/constants.py"
    click buy_game "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/buy_sell_game/game.py"
    click buy_prompt "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/buy_sell_game/prompt.py"
    click simple_game "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/simple_game/game.py"
    click simple_prompt "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/simple_game/prompt.py"
    click trade_game "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/trading_game/game.py"
    click trade_interface "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/trading_game/interface.py"
    click trade_prompt "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/trading_game/prompt.py"
    click ult_game "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/ultimatum/game.py"
    click ult_interface "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/ultimatum/interface.py"
    click ult_prompt "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/games/ultimatum/prompt.py"
    click obj_game "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/game_objects/game.py"
    click obj_goal "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/game_objects/goal.py"
    click obj_resource "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/game_objects/resource.py"
    click obj_trade "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/game_objects/trade.py"
    click obj_valuation "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/game_objects/valuation.py"
    click agent_msg "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/agent_message.py"
    click agent_behav "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/agents/agent_behaviours.py"
    click agent_base "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/agents/agents.py"
    click agent_chat "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/agents/chatgpt.py"
    click agent_claude "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/agents/claude.py"
    click agent_llama2 "https://github.com/zou-group/sirius/blob/main/Competitive/NegotiationArena/negotiationarena/agents/llama2.py"

    %% Styles
    classDef entry fill:#cccccc,stroke:#333,stroke-width:1px
    classDef runner fill:#bbbbbb,stroke:#333,stroke-width:1px
    classDef core fill:#a8ddb5,stroke:#333,stroke-width:1px
    classDef scenario fill:#9ecae1,stroke:#333,stroke-width:1px
    classDef objects fill:#fdbb84,stroke:#333,stroke-width:1px
    classDef agent fill:#bc80bd,stroke:#333,stroke-width:1px
    classDef external fill:#fdae6b,stroke:#333,stroke-width:1px
```
