# facebookresearch/diplomacy_cicero architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/diplomacy_cicero
- Repository: https://github.com/facebookresearch/diplomacy_cicero

## Overview

##### Project Type and Purpose
- The project is a research platform that integrates language models with reinforcement learning and strategic reasoning to play the game of Diplomacy. It contains code for strategic planning (Cicero and Diplodocus), simulation of games, training using RL and supervised learning, and even parts of a full-stack such as front-end game visualizers.
- It leverages the ParlAI framework for language modeling; uses Python for high-level agent design, model training, and selfplay simulation; and contains performance-critical components implemented in C++ (via the dipcc directory) that are integrated via pybind.

##### Analyzing the File Structure
- Directories like "parlai_diplomacy" and "fairdiplomacy" house language modeling, strategic planning (agents, model training, and RL training through selfplay), and configuration files.
- The "conf" directory holds protobuf configurations that drive different modes (simulation, training, comparison) using a configuration framework called HeyHi.
- The "dipcc" directory includes C++ code for core game functions (e.g., adjudication, serialization) and a pybind interface connecting with Python.
- Additional directories such as "fairdiplomacy_external" and "heyhi" provide external UI utilities and configuration helpers.
- There are robust testing directories (unit_tests) and CI/CD integration (inside .circleci) that ensure code quality and correct behavior.

##### Key Components
- Agent Components:
- Strategic Planning Agents (found in fairdiplomacy/agents) that implement core planning algorithms (e.g., br_corr_bilateral_search.py and bqre1p_agent.py).
- Additional helper agents, dialogue agents, and imitation agents built into the same ecosystem.
- Model Training & RL Components:
- The training pipeline for both supervised learning and RL (e.g., in fairdiplomacy/models/base_strategy_model and fairdiplomacy/selfplay).
- Reinforcement learning training and selfplay simulation, including data processing and distributed training logic.
- Configuration and Runtime Execution:
- A configuration subsystem (using HeyHi, with configs stored in the conf directory and utilized by run.py) that takes protobuf inputs to specify tasks (like training or simulation).
- The central entry point “run.py” which dispatches tasks based on the provided configuration.
- Simulation Engine and C++ Performance Module:
- The dipcc directory contains the C++ core game simulation engine (e.g., game state, adjudication, ordering) with pybind bindings that allow Python to interface with high-performance C++ code.
- External Modules and Utilities:
- ParlAI integration (in parlai_diplomacy) for language modeling and agent interactions.
- External visualization utilities present in fairdiplomacy_external and heyhi for game rendering.
- Supporting scripts in bin for various tasks such as checking configs, compiling, and model file handling.
- Data and Config Management:
- The “data” directory for game data (including game records and order vocab files).
- The “conf” directory for all experiment and task-specific configuration (including agent schema and training parameters).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration & Dispatch"
        A("Run Dispatcher (run.py)"):::config
        B("Configuration Files (conf)"):::config
        C("Config Helpers (heyhi)"):::config
    end

    subgraph "Model Training & RL"
        D("Base Strategy Model"):::training
        E("Selfplay Simulation"):::training
    end

    subgraph "Agent Modules"
        F("Agent Strategic Planning"):::agent
        G("Language Modeling (ParlAI)"):::agent
    end

    subgraph "Simulation Engine"
        H("C++ Simulation Engine"):::simulation
    end

    subgraph "External Tools & Visualization"
        I("Visualization Tools"):::external
    end

    subgraph "Data & Utilities"
        J("Data Management"):::data
        K("Utility Scripts"):::utility
    end

    L("External Libraries<br/>(PyTorch,CUDA,pybind11,Protobuf)"):::dependencies

    %% Connections
    A -->|"dispatches"| D
    A -->|"dispatches"| E
    A -->|"triggers"| F
    D -->|"trains"| F
    E -->|"triggers simulation"| H
    F -->|"interfaces with"| H
    G -->|"integrates with"| F
    J -->|"supplies data to"| D
    J -->|"supplies data to"| E
    I -->|"supports UX for"| A
    L --> D
    L --> E
    L --> F
    L --> H

    %% Click Events
    click A "https://github.com/facebookresearch/diplomacy_cicero/blob/main/run.py"
    click B "https://github.com/facebookresearch/diplomacy_cicero/tree/main/conf"
    click C "https://github.com/facebookresearch/diplomacy_cicero/tree/main/heyhi/"
    click D "https://github.com/facebookresearch/diplomacy_cicero/tree/main/fairdiplomacy/models/base_strategy_model"
    click E "https://github.com/facebookresearch/diplomacy_cicero/tree/main/fairdiplomacy/selfplay"
    click F "https://github.com/facebookresearch/diplomacy_cicero/tree/main/fairdiplomacy/agents"
    click G "https://github.com/facebookresearch/diplomacy_cicero/tree/main/parlai_diplomacy"
    click H "https://github.com/facebookresearch/diplomacy_cicero/tree/main/dipcc"
    click I "https://github.com/facebookresearch/diplomacy_cicero/tree/main/fairdiplomacy_external"
    click J "https://github.com/facebookresearch/diplomacy_cicero/tree/main/data"
    click K "https://github.com/facebookresearch/diplomacy_cicero/tree/main/bin"

    %% Styles
    classDef config fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef training fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef agent fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef simulation fill:#FFCCCB,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef data fill:#FFD699,stroke:#000,stroke-width:2px;
    classDef utility fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef dependencies fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
