L-GRAFT: GraphRAG-Guided Communication Topology Learning for MARL

English | 中文

L-GRAFT learns sparse, task-adaptive communication topologies for cooperative multi-agent reinforcement learning via GraphRAG-guided LLM reasoning. Built on QMIX + CommNet, it retrieves historical topology evidence, proposes sparse directed graphs with an LLM, and injects the selected topology as a communication mask.

Installation

# 1. Environment
conda create -n lgraft python=3.10 -y
conda activate lgraft

# 2. PyTorch (adjust CUDA version as needed)
pip install torch>=2.0.0

# 3. SMAC and dependencies
pip install git+https://github.com/oxwhirl/smac.git
pip install -r requirements.txt

# 4. StarCraft II binary (Linux / headless)
bash scripts/install_sc2.sh
export SC2PATH=$(pwd)/.sc2_cache/StarCraftII

Quick Start

Train L-GRAFT on a single map:

python src/main_train.py --config configs/default.yaml --map_name 3s5z

Train baselines:

python src/main_train.py --config configs/default.yaml --map_name 3s5z --baseline qmix
python src/main_train.py --config configs/default.yaml --map_name 3s5z --baseline fullcomm

Evaluate a checkpoint:

python src/main_eval.py --config configs/default.yaml --map_name 3s5z \
    --checkpoint checkpoints/3s5z/lgraft/seed0_final.pt

Reproducing Paper Results

Run the full experimental pipeline:

bash scripts/train_lgraft.sh      # L-GRAFT on 13 SMAC maps × 5 seeds
bash scripts/train_baselines.sh   # QMIX / FullComm / CommNet baselines
bash scripts/eval_all.sh          # Evaluate and summarize
bash scripts/run_ablations.sh     # Component ablations
bash scripts/run_restricted_sight.sh  # Restricted-sight robustness

Use configs/qwen.yaml to switch to the Qwen/DashScope LLM backend, or set llm.backend: mock in the config to run without an API key.

Repository Structure

l-graft/
├── configs/          # YAML configs (default, qwen, sight6)
├── docs/             # Project page and architecture notes
├── scripts/          # Training / evaluation / ablation scripts
├── src/              # Source code (envs, marl, memory, llm, selector)
├── tests/            # Unit tests
├── checkpoints/      # Saved models (git-ignored)
└── results/          # Logs and CSVs (git-ignored)

Citation

@inproceedings{lgraft2026icdm,
  title     = {L-GRAFT: GraphRAG-Guided Communication Topology Learning for Multi-Agent Reinforcement Learning},
  author    = {Yi Shen and Jiaxu Li and Yahong Han},
  booktitle = {IEEE International Conference on Data Mining (ICDM)},
  year      = {2026},
  organization = {Tianjin University}
}

License

MIT