# copticoder/mt-via-round-trip-rl architecture

> Architecture diagram of the GitHub repository copticoder/mt-via-round-trip-rl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/copticoder/mt-via-round-trip-rl
- Repository: https://github.com/copticoder/mt-via-round-trip-rl

## Overview

1. **Project purpose**
   This repo is a research training pipeline for low-resource machine translation, centered on a round-trip reinforcement-learning fine-tuning method for NLLB models. The core experiment is: translate English to a low-resource language, translate back to English, and reward the model based on reconstruction quality.

2. **Top-level architecture**
   The repository splits into two main areas:
   - the **main training/evaluation pipeline** in `main.py`, `dl.py`, and `utils.py`
   - **baseline implementations** under `baselines/` for backtranslation and UMNMT comparisons
   This separation makes the main method and the comparison methods independently runnable.

3. **Orchestrator layer**
   `main.py` is the central entry point. It coordinates:
   - configuration loading
   - dataset/model setup
   - training loop
   - validation/test evaluation
   - experiment logging
   It is the primary place where data flow and control flow converge.

4. **Data ingestion boundary**
   `dl.py` isolates dataset loading for the NLLB-MD benchmark. This keeps dataset-specific logic out of the training loop and makes it easier to swap task/data settings through configuration rather than code changes.

5. **Training logic and reward/loss computation**
   `utils.py` contains shared helpers plus the GRPO loss function used for the reinforcement-learning-style fine-tuning. Architecturally, this file sits between model outputs and optimization, converting translation quality signals into a training objective.

6. **Configuration subsystem**
   `configs/` is organized into layered configuration groups:
   - `configs/train.yaml` for overall training defaults
   - `configs/task/` for dataset/task selection
   - `configs/device/` for hardware-specific settings
   - `configs/hydra/default.yaml` for Hydra behavior
   This indicates a config-driven architecture where environment and experiment variants are selected without changing code.

7. **Device and runtime portability**
   The device configs include `cpu`, `gpu`, `mps`, `a100`, and `a100l`, which suggests the pipeline is intended to run across local machines and multiple accelerator types. Hardware-specific behavior is handled through configuration rather than separate code paths.

8. **Model and experiment scope**
   The core experiment targets NLLB models, specifically the 600M and 1.3B variants mentioned in the README. The architecture is therefore centered on fine-tuning pretrained translation models rather than training MT models from scratch.

9. **Evaluation and logging flow**
   Evaluation on validation and test sets happens during and after training, so the system is not just a training script but a full experiment loop. The README also references Weights & Biases, so experiment metrics and plots are logged externally for analysis.

10. **Baseline subsystem**
   `baselines/` contains separate implementations for:
   - `backtranslation`
   - `roundtrip-bt`
   - `UMNMT`
   Each baseline has its own Python entry point and shell launcher, which means the comparison methods are intentionally decoupled from the main RL pipeline.

11. **Execution model**
   The repo is run as a Python experiment project, typically via `python main.py`, with shell scripts used for baseline runs. This implies a workflow where the primary unit of execution is a configured training job rather than a long-running service or API.

12. **How to draw the architecture**
   A good architecture diagram would show:
   - configuration inputs feeding the main training job
   - dataset loading via `dl.py`
   - model/training/reward computation in `main.py` + `utils.py`
   - logging/evaluation as side outputs
   - separate baseline pipelines under `baselines/`
   The main boundary is between the configurable RL training system and the independent baseline experiment runners.

Main entry points: [`main.py`](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/main.py) (Main job), [`baselines/backtranslation/backtranslation.py`](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/backtranslation/backtranslation.py) (Backtranslation), [`baselines/roundtrip-bt/roundtrip-bt.py`](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/roundtrip-bt/roundtrip-bt.py) (Roundtrip BT), [`baselines/UMNMT/umnmt.py`](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/UMNMT/umnmt.py) (UMNMT)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["Main pipeline"]
  node_main_py["Main job<br/>orchestrator<br/>[main.py]"]
  node_dl_py["Data loader<br/>dataset boundary<br/>[dl.py]"]
  node_utils_py["RL utils<br/>loss/helpers<br/>[utils.py]"]
  node_nllb_model[("NLLB model<br/>pretrained MT model")]
  node_eval_loop(("Eval loop<br/>validation/test"))
  node_wandb(("W&B logs<br/>experiment tracking"))
end

subgraph group_cfg["Configs"]
  node_train_yaml["Train config<br/>experiment defaults<br/>[train.yaml]"]
  node_task_yaml["Task config<br/>dataset/task selector<br/>[nllb_md.yaml]"]
  node_device_cfgs["Device presets<br/>runtime config set"]
  node_hydra_yaml["Hydra config<br/>config runtime<br/>[default.yaml]"]
end

subgraph group_base["Baselines"]
  node_bt_py["Backtranslation<br/>baseline runner<br/>[backtranslation.py]"]
  node_rtbt_py["Roundtrip BT<br/>baseline runner<br/>[roundtrip-bt.py]"]
  node_umnmt_py["UMNMT<br/>baseline runner<br/>[umnmt.py]"]
  node_bt_sh["BT script<br/>launcher"]
  node_rtbt_sh["RTBT script<br/>launcher"]
  node_umnmt_sh["UMNMT script<br/>launcher<br/>[run_training.sh]"]
  node_base_utils["Baseline utils<br/>shared helpers<br/>[utils.py]"]
end

node_train_yaml -->|"defaults"| node_main_py
node_task_yaml -->|"task"| node_main_py
node_device_cfgs -->|"runtime"| node_main_py
node_hydra_yaml -->|"compose"| node_main_py
node_main_py -->|"load data"| node_dl_py
node_main_py -->|"optimize"| node_utils_py
node_main_py -->|"fine-tune"| node_nllb_model
node_main_py -->|"validate"| node_eval_loop
node_main_py -->|"log"| node_wandb
node_bt_sh -->|"run"| node_bt_py
node_rtbt_sh -->|"run"| node_rtbt_py
node_umnmt_sh -->|"run"| node_umnmt_py
node_bt_py -->|"shared code"| node_base_utils
node_rtbt_py -->|"shared code"| node_base_utils
node_umnmt_py -->|"shared code"| node_base_utils
node_bt_py -.->|"compare"| node_eval_loop
node_rtbt_py -.->|"compare"| node_eval_loop
node_umnmt_py -.->|"compare"| node_eval_loop

click node_main_py "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/main.py"
click node_dl_py "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/dl.py"
click node_utils_py "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/utils.py"
click node_train_yaml "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/configs/train.yaml"
click node_task_yaml "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/configs/task/nllb_md.yaml"
click node_hydra_yaml "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/configs/hydra/default.yaml"
click node_bt_py "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/backtranslation/backtranslation.py"
click node_rtbt_py "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/roundtrip-bt/roundtrip-bt.py"
click node_umnmt_py "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/UMNMT/umnmt.py"
click node_bt_sh "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/backtranslation/run_backtranslation.sh"
click node_rtbt_sh "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/roundtrip-bt/run_roundtrip_bt.sh"
click node_umnmt_sh "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/UMNMT/run_training.sh"
click node_base_utils "https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/utils.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_main_py,node_dl_py,node_utils_py,node_nllb_model,node_eval_loop,node_wandb toneBlue
class node_train_yaml,node_task_yaml,node_device_cfgs,node_hydra_yaml toneAmber
class node_bt_py,node_rtbt_py,node_umnmt_py,node_bt_sh,node_rtbt_sh,node_umnmt_sh,node_base_utils toneMint
```

## Components

### Main pipeline

Config-driven RL fine-tuning and evaluation flow

- [Main job](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/main.py): orchestrator · Central training and evaluation entry point · `main.py`
- [Data loader](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/dl.py): dataset boundary · Loads the NLLB-MD benchmark and task data · `dl.py`
- [RL utils](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/utils.py): loss/helpers · Shared helpers and GRPO-style loss computation · `utils.py`
- **NLLB model**: pretrained MT model · Fine-tuned translation backbone used by the main experiment
- **Eval loop**: validation/test · Validation and test evaluation during training
- **W&B logs**: experiment tracking · External metric and run logging

### Configs

Hydra-based experiment and runtime selection

- [Train config](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/configs/train.yaml): experiment defaults · Top-level training defaults · `configs/train.yaml`
- [Task config](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/configs/task/nllb_md.yaml): dataset/task selector · Task and dataset selection for NLLB-MD · `configs/task/nllb_md.yaml`
- **Device presets**: runtime config set · CPU, GPU, MPS, A100, and A100L hardware profiles
- [Hydra config](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/configs/hydra/default.yaml): config runtime · Hydra defaults and config behavior · `configs/hydra/default.yaml`

### Baselines

Independent comparison pipelines

- [Backtranslation](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/backtranslation/backtranslation.py): baseline runner · Standalone backtranslation baseline implementation · `baselines/backtranslation/backtranslation.py`
- [Roundtrip BT](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/roundtrip-bt/roundtrip-bt.py): baseline runner · Standalone round-trip backtranslation baseline implementation · `baselines/roundtrip-bt/roundtrip-bt.py`
- [UMNMT](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/UMNMT/umnmt.py): baseline runner · Standalone UMNMT baseline implementation · `baselines/UMNMT/umnmt.py`
- [BT script](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/backtranslation/run_backtranslation.sh): launcher · Shell launcher for the backtranslation baseline · `baselines/backtranslation/run_backtranslation.sh`
- [RTBT script](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/roundtrip-bt/run_roundtrip_bt.sh): launcher · Shell launcher for the roundtrip baseline · `baselines/roundtrip-bt/run_roundtrip_bt.sh`
- [UMNMT script](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/UMNMT/run_training.sh): launcher · Shell launcher for the UMNMT baseline · `baselines/UMNMT/run_training.sh`
- [Baseline utils](https://github.com/copticoder/mt-via-round-trip-rl/blob/src-tgt-src-outcome/baselines/utils.py): shared helpers · Shared baseline support code · `baselines/utils.py`

## Connections

- Train config → Main job: defaults · Provides core training configuration
- Task config → Main job: task · Selects the dataset/task variant
- Device presets → Main job: runtime · Chooses the target hardware profile
- Hydra config → Main job: compose · Controls Hydra composition and overrides
- Main job → Data loader: load data · Delegates benchmark data ingestion
- Main job → RL utils: optimize · Uses shared helpers and GRPO loss
- Main job → NLLB model: fine-tune · Runs round-trip RL fine-tuning on the pretrained model
- Main job → Eval loop: validate · Performs validation and test evaluation
- Main job → W&B logs: log · Sends metrics and experiment outputs to tracking
- BT script → Backtranslation: run · Launches the backtranslation baseline
- RTBT script → Roundtrip BT: run · Launches the roundtrip backtranslation baseline
- UMNMT script → UMNMT: run · Launches the UMNMT baseline
- Backtranslation → Baseline utils: shared code · Reuses common baseline utilities
- Roundtrip BT → Baseline utils: shared code · Reuses common baseline utilities
- UMNMT → Baseline utils: shared code · Reuses common baseline utilities
- Backtranslation → Eval loop: compare · Produces baseline experiment outputs for comparison
- Roundtrip BT → Eval loop: compare · Produces baseline experiment outputs for comparison
- UMNMT → Eval loop: compare · Produces baseline experiment outputs for comparison
