# denispeskoff/2020_acl_diplomacy architecture

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

- Interactive diagram: https://gitdiagram.com/denispeskoff/2020_acl_diplomacy
- Repository: https://github.com/denispeskoff/2020_acl_diplomacy

## Overview

##### Project type and purpose
- This is a research codebase (ACL 2020) for “It Takes Two to Lie: One to Lie, and One to Listen.”
- Its goal is to train and evaluate neural models (via allennlp) to detect lies in the board‐game Diplomacy dialogue dataset.

##### File structure
- Top‐level items:
- configs/ – allennlp JSONNET configs for different model variants (e.g., bert+context, lstm) split into actual_lie vs. suspected_lie setups
- data/ – train/validation/test message files in JSONL
- moves/ – full game state files (unused by the core paper models)
- diplomacy/ – Python package with two subpackages:
– models/ – implementations of classifier architectures and baselines
– readers/ – data loaders for game state and message streams
- utils/ – preprocessing script to convert single‐message data into the format expected by LSTM models
- run_models.sh – wrapper to launch multiple experiments
- setup.py, requirements.txt – packaging and dependencies
- Signals: an ML‐centric pipeline built on allennlp, with clear separation of configuration, data reading, modeling, and experiment orchestration.

##### Extract insights from README
- Uses conda + pip install -e .
- Trains via:
allennlp train -f --include-package diplomacy -s logdir configs/...jsonnet
- Lists two major pipelines: a “single‐message” LSTM (requires preprocessing via utils) and multi‐message/context‐based classifiers.

a. Main components
- External tools: Conda/Python runtime, allennlp framework
- Configuration layer: configs/{actual_lie,suspected_lie}/*.jsonnet
- Data layer:
– Raw message data (data/*.jsonl)
– Full game JSON files (moves/*.json)
- Preprocessing: utils/singlemessage_format.py → formatted JSONL for LSTM
- Readers: diplomacy/readers/{message_reader, game_reader}
- Model implementations: diplomacy/models/*.py
- Experiment orchestrator: run_models.sh & allennlp CLI
- Output: logdir/ (metrics, model checkpoints)
b. Relationships & data flow
1. configs load hyperparameters & dataset paths
2. allennlp CLI invokes diplomacy.readers to parse data
3. Data passes to diplomacy.models classes (embedding → encoding → classifier head)
4. Training/Evaluation emits metrics and model artifacts to logdir
c. Architectural patterns & design principles
- Modular ML pipeline: clear separation of config, data I/O, model code, and experiment scripts
- Plug‐and‐play model variants via config files
- Reusable readers abstracting message vs. game state ingestion
d. Key technologies
- allennlp for training loop and configuration management
- PyTorch (via allennlp) for model implementations
- JSON/JSONL for data interchange
- Jsonnet for parameterized configs

##### Detailed capture
- Of the eight model files under diplomacy/models is represented as a variant node connected to the shared reader.
- That configs select which model class to instantiate.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        D1["data/train.jsonl"]:::data-blue
        D2["data/validation.jsonl"]:::data-blue
        D3["data/test.jsonl"]:::data-blue
        D4["moves/*.json"]:::data-blue
    end

    %% Preprocessing
    subgraph "Preprocessing"
        PM["utils/singlemessage_format.py"]:::prep-green
        PL["utils/2015_Diplomacy_lexicon.json"]:::prep-green
        FD["Formatted Data (JSONL)"]:::prep-green
    end

    %% Reading Layer
    subgraph "Data Ingestion"
        MR["message_reader.py"]:::reader-green
        GR["game_reader.py"]:::reader-green
    end

    %% Model Implementations
    subgraph "Model Implementations"
        M1["bagofwords.py"]:::model-orange
        M2["harbringers.py"]:::model-orange
        M3["hlstm.py"]:::model-orange
        M4["human_baseline.py"]:::model-orange
        M5["lie_detector.py"]:::model-orange
        M6["pooled_rnn.py"]:::model-orange
        M7["random_and_majority_baselines.py"]:::model-orange
    end

    %% Configuration
    subgraph "Configuration Layer"
        C1["configs/actual_lie/bert+context.jsonnet"]:::config-yellow
        C2["configs/actual_lie/contextlstm.jsonnet"]:::config-yellow
        C3["configs/actual_lie/lstm.jsonnet"]:::config-yellow
        C4["configs/suspected_lie/bert+context.jsonnet"]:::config-yellow
        C5["configs/suspected_lie/contextlstm.jsonnet"]:::config-yellow
        C6["configs/suspected_lie/lstm.jsonnet"]:::config-yellow
    end

    %% Orchestration
    subgraph "Orchestration"
        OMS["run_models.sh"]:::orch-purple
        ALLEN["allennlp CLI"]:::orch-purple
    end

    %% Output
    subgraph "Output"
        OUT["logdir/"]:::output-grey
    end

    %% Connections
    D1 --> PM
    D2 --> PM
    D3 --> PM
    PM --> FD
    FD --> MR
    D4 --> GR

    ALLEN --> MR
    ALLEN --> GR
    MR --> M1
    MR --> M2
    MR --> M3
    MR --> M4
    MR --> M5
    MR --> M6
    MR --> M7
    GR --> M1
    GR --> M2
    GR --> M3
    GR --> M4
    GR --> M5
    GR --> M6
    GR --> M7

    M1 --> OUT
    M2 --> OUT
    M3 --> OUT
    M4 --> OUT
    M5 --> OUT
    M6 --> OUT
    M7 --> OUT

    OMS --> ALLEN
    C1 -.-> ALLEN
    C2 -.-> ALLEN
    C3 -.-> ALLEN
    C4 -.-> ALLEN
    C5 -.-> ALLEN
    C6 -.-> ALLEN

    %% Click Events
    click C1 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/configs/actual_lie/bert+context.jsonnet"
    click C2 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/configs/actual_lie/contextlstm.jsonnet"
    click C3 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/configs/actual_lie/lstm.jsonnet"
    click C4 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/configs/suspected_lie/bert+context.jsonnet"
    click C5 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/configs/suspected_lie/contextlstm.jsonnet"
    click C6 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/configs/suspected_lie/lstm.jsonnet"
    click D1 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/data/train.jsonl"
    click D2 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/data/validation.jsonl"
    click D3 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/data/test.jsonl"
    click D4 "https://github.com/denispeskoff/2020_acl_diplomacy/tree/master/moves"
    click PM "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/utils/singlemessage_format.py"
    click PL "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/utils/2015_Diplomacy_lexicon.json"
    click MR "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/readers/message_reader.py"
    click GR "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/readers/game_reader.py"
    click M1 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/models/bagofwords.py"
    click M2 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/models/harbringers.py"
    click M3 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/models/hlstm.py"
    click M4 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/models/human_baseline.py"
    click M5 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/models/lie_detector.py"
    click M6 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/models/pooled_rnn.py"
    click M7 "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/diplomacy/models/random_and_majority_baselines.py"
    click OMS "https://github.com/denispeskoff/2020_acl_diplomacy/blob/master/run_models.sh"

    %% Styles
    classDef data-blue fill:#228BE6,stroke:#000,color:#fff
    classDef prep-green fill:#28A745,stroke:#000,color:#fff
    classDef reader-green fill:#20C997,stroke:#000,color:#fff
    classDef model-orange fill:#FD7E14,stroke:#000,color:#fff
    classDef config-yellow fill:#FFC107,stroke:#000,color:#000
    classDef orch-purple fill:#6F42C1,stroke:#000,color:#fff
    classDef output-grey fill:#6C757D,stroke:#000,color:#fff
```
