# xiewilliams/marco architecture

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

- Interactive diagram: https://gitdiagram.com/xiewilliams/marco
- Repository: https://github.com/xiewilliams/marco

## Overview

MARCO turns multi-domain review data into target-domain recommendation data, then trains a recommender whose source-domain contributions are selected cooperatively by multi-agent reinforcement learning. The primary runtime is entry.py → run.py: Run prepares loaders and models, coordinates the RL environment and MAPPO trainer, and uses inference to produce predictions and contribution weights. Separate branches cover review preprocessing and single-domain MF pretraining. The graph reflects the README and sampled source; some Run methods and model details were omitted, so uncertain internal wiring is not expanded.

Main entry points: [`run.py`](https://github.com/xiewilliams/marco/blob/main/run.py) (Experiment orchestration), [`rl_trainer_infer.py`](https://github.com/xiewilliams/marco/blob/main/rl_trainer_infer.py) (Training and inference), [`singleMF/singlepre.py`](https://github.com/xiewilliams/marco/blob/main/singleMF/singlepre.py) (Single-domain MF), [`entry.py`](https://github.com/xiewilliams/marco/blob/main/entry.py) (Training entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_preprocess["Review preprocessing<br/>[preprocess.py]"]
  node_prepared["Domain datasets"]
end

subgraph group_pretrain["Domain pretraining"]
  node_mfpretrain["Single-domain MF<br/>[singlepre.py]"]
  node_mfconfig["MF settings<br/>[config.json]"]
  node_pretrained["Pretrained models"]
end

subgraph group_runtime["Recommendation runtime"]
  node_entry["Training entry<br/>[entry.py]"]
  node_config["MARCO settings<br/>[config.json]"]
  node_run["Experiment orchestration<br/>[run.py]"]
  node_models["Recommendation models<br/>[models.py]"]
  node_trainer["Training and inference"]
  node_predictions["Ratings and weights"]
end

subgraph group_rl["Cooperative learning"]
  node_environment["CDR environment<br/>[rl_environment.py]"]
  node_mappo["MAPPO agents<br/>[MAPPO.py]"]
end

node_engineer(("Researcher"))
node_reviews["Amazon reviews"]

node_engineer -->|"starts training"| node_entry
node_engineer -->|"prepares data"| node_preprocess
node_engineer -->|"pretrains domains"| node_mfpretrain
node_reviews -->|"supplies reviews"| node_preprocess
node_preprocess -->|"parses and splits"| node_prepared
node_prepared -->|"loads interaction data"| node_run
node_mfconfig -->|"configures"| node_mfpretrain
node_mfpretrain -->|"reads domain data"| node_prepared
node_mfpretrain -->|"saves embeddings"| node_pretrained
node_entry -->|"loads settings"| node_config
node_entry -->|"starts experiment"| node_run
node_pretrained -->|"provides model paths"| node_run
node_run -->|"constructs recommender"| node_models
node_run -->|"runs training and inference"| node_trainer
node_trainer -->|"resets and steps"| node_environment
node_trainer -->|"selects actions and trains"| node_mappo
node_environment -->|"requests embeddings"| node_models
node_environment -->|"computes weighted predictions"| node_models
node_trainer -->|"returns predictions and weights"| node_predictions

click node_preprocess "https://github.com/xiewilliams/marco/blob/main/preprocessing/preprocess.py"
click node_mfpretrain "https://github.com/xiewilliams/marco/blob/main/singleMF/singlepre.py"
click node_mfconfig "https://github.com/xiewilliams/marco/blob/main/singleMF/config.json"
click node_entry "https://github.com/xiewilliams/marco/blob/main/entry.py"
click node_config "https://github.com/xiewilliams/marco/blob/main/config.json"
click node_run "https://github.com/xiewilliams/marco/blob/main/run.py"
click node_models "https://github.com/xiewilliams/marco/blob/main/models.py"
click node_trainer "https://github.com/xiewilliams/marco/blob/main/rl_trainer_infer.py"
click node_environment "https://github.com/xiewilliams/marco/blob/main/rl_environment.py"
click node_mappo "https://github.com/xiewilliams/marco/blob/main/MAPPO.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_preprocess,node_prepared,node_reviews toneBlue
class node_mfpretrain,node_mfconfig,node_pretrained toneAmber
class node_entry,node_config,node_run,node_models,node_trainer,node_predictions toneMint
class node_environment,node_mappo toneRose
class node_engineer toneIndigo
```

## Components

### Data preparation

- [Review preprocessing](https://github.com/xiewilliams/marco/blob/main/preprocessing/preprocess.py): `preprocessing/preprocess.py`
- **Domain datasets**

### Domain pretraining

- [Single-domain MF](https://github.com/xiewilliams/marco/blob/main/singleMF/singlepre.py): `singleMF/singlepre.py`
- [MF settings](https://github.com/xiewilliams/marco/blob/main/singleMF/config.json): `singleMF/config.json`
- **Pretrained models**

### Recommendation runtime

- [Training entry](https://github.com/xiewilliams/marco/blob/main/entry.py): `entry.py`
- [MARCO settings](https://github.com/xiewilliams/marco/blob/main/config.json): `config.json`
- [Experiment orchestration](https://github.com/xiewilliams/marco/blob/main/run.py): `run.py`
- [Recommendation models](https://github.com/xiewilliams/marco/blob/main/models.py): `models.py`
- [Training and inference](https://github.com/xiewilliams/marco/blob/main/rl_trainer_infer.py): `rl_trainer_infer.py`
- **Ratings and weights**

### Cooperative learning

- [CDR environment](https://github.com/xiewilliams/marco/blob/main/rl_environment.py): `rl_environment.py`
- [MAPPO agents](https://github.com/xiewilliams/marco/blob/main/MAPPO.py): `MAPPO.py`

### Other components

- **Researcher**
- **Amazon reviews**

## Connections

- Researcher → Training entry: starts training
- Researcher → Review preprocessing: prepares data
- Researcher → Single-domain MF: pretrains domains
- Amazon reviews → Review preprocessing: supplies reviews
- Review preprocessing → Domain datasets: parses and splits
- Domain datasets → Experiment orchestration: loads interaction data
- MF settings → Single-domain MF: configures
- Single-domain MF → Domain datasets: reads domain data
- Single-domain MF → Pretrained models: saves embeddings
- Training entry → MARCO settings: loads settings
- Training entry → Experiment orchestration: starts experiment
- Pretrained models → Experiment orchestration: provides model paths
- Experiment orchestration → Recommendation models: constructs recommender
- Experiment orchestration → Training and inference: runs training and inference
- Training and inference → CDR environment: resets and steps
- Training and inference → MAPPO agents: selects actions and trains
- CDR environment → Recommendation models: requests embeddings
- CDR environment → Recommendation models: computes weighted predictions
- Training and inference → Ratings and weights: returns predictions and weights