# dvlab-research/motcoder architecture

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

- Interactive diagram: https://gitdiagram.com/dvlab-research/motcoder
- Repository: https://github.com/dvlab-research/motcoder

## Overview

##### Project type and purpose
- MoTCoder is a research codebase for instruction‐tuning large language models (LLMs) with a “Modular of Thought” framework.
- It consists of two main pipelines:
- Training (using LLaMA-Factory + YAML configs)
- Evaluation (using Hugging Face datasets, vLLM wrappers, custom scripts)

##### Main components
A. External Resources / Data Stores
- HF Hub Datasets: APPS, CodeContests
- HF Hub Models: MoTCoder‐7B, ‐32B, ‐72B
- Local “motcode” dataset (350K examples)
B. Training Pipeline
- LLaMA-Factory framework (cloned from GitHub)
- train/configs/*.yaml (hyperparams & model‐specific settings)
- train/scripts/*.sh (entrypoints: run.sh, run_1gpu.sh, etc.)
- Compute Layer: GPU cluster or single‐GPU node
- Outputs: fine-tuned model checkpoints
C. Evaluation Pipeline
- eval/dataset (data prep: data.py, prompts.py)
- eval/eval.py (evaluation harness)
- eval/vllm_gen.py & eval/vllm_fix.py (vLLM integration for generation & self‐correction)
- eval/scripts/*.sh (batch evaluation for APPS, CodeContests, fix tasks)
- eval/testing_util.py & eval/utils.py (metric computation & logging)
- Outputs: performance metrics, pass@1 results
D. Supporting Files
- .gitignore, Readme.md, imgs/ (documentation and visuals)

##### Relationships and data flows
- Data Flow for Training:
1. “motcode” dataset (HF Hub) → LLaMA-Factory data loader
3. LLaMA-Factory trains → GPU cluster → produces model checkpoints → optionally pushed to HF Hub
- Data Flow for Evaluation:
1. Download APPS & CodeContests → local data/ directory
2. eval/dataset/data.py transforms raw data → standardized prompts
3. eval scripts invoke eval/eval.py → load MoTCoder checkpoint
4. vLLM wrappers generate predictions + self‐corrections
5. utils/testing_util.py computes pass@1 and other metrics → logs/results

##### Architectural patterns & design principles
- Pipeline separation: clear division between training vs. evaluation
- Configuration‐driven: YAML configs decouple code from hyperparameters
- Modular code: distinct Python modules for data prep, generation, fixing, and utilities
- Reproducibility: shell scripts capture standard commands for various GPU setups

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Resources
    subgraph "External Resources"
        direction TB
        HF_Datasets["HF Hub Datasets<br/>APPS, CodeContests"]:::external
        HF_Models["HF Hub Models<br/>MoTCoder-7B, ‑32B, ‑72B"]:::external
        Local_Dataset["Local motcode Dataset<br/>350K examples"]:::data
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        direction TB
        Configs["train/configs/ (YAML configs)"]:::code
        Scripts["train/scripts/ (entrypoint scripts)"]:::code
        LLaMA["LLaMA-Factory Framework"]:::external
        Compute["GPU Cluster/Node"]:::infra
        Checkpoints["Model Checkpoints"]:::data
    end

    %% Evaluation Pipeline
    subgraph "Evaluation Pipeline"
        direction TB
        DataPrep["eval/dataset/data.py & prompts.py"]:::code
        EvalHarness["eval/eval.py"]:::code
        Gen["vLLM Generation<br/>(eval/vllm_gen.py)"]:::code
        Fix["vLLM Self-Correction<br/>(eval/vllm_fix.py)"]:::code
        EvalScripts["eval/scripts/*.sh"]:::code
        Utils["testing_util.py & utils.py"]:::code
        Metrics["Performance Metrics<br/>pass@1, logs"]:::data
    end

    %% Supporting Files
    subgraph "Supporting Files"
        direction TB
        GitIgnore[".gitignore"]:::code
        Readme["Readme.md"]:::code
        Images["imgs/"]:::code
    end

    %% Connections: Training Flow
    Local_Dataset -->|"load data"| LLaMA
    Configs -->|"configs"| LLaMA
    Scripts -->|"start training"| LLaMA
    LLaMA -->|"train on"| Compute
    Compute -->|"produce"| Checkpoints
    Checkpoints -->|"push to"| HF_Models

    %% Connections: Evaluation Flow
    HF_Datasets -->|"download data"| DataPrep
    Checkpoints -->|"load model"| EvalHarness
    EvalScripts -->|"invoke"| EvalHarness
    DataPrep -->|"prepare prompts"| EvalHarness
    EvalHarness -->|"generate"| Gen
    EvalHarness -->|"self-correct"| Fix
    Gen -->|"predictions"| Utils
    Fix -->|"refined outputs"| Utils
    Utils -->|"compute metrics"| Metrics

    %% Click Events
    click Configs "https://github.com/dvlab-research/motcoder/tree/master/train/configs/"
    click Scripts "https://github.com/dvlab-research/motcoder/tree/master/train/scripts/"
    click DataPrep "https://github.com/dvlab-research/motcoder/blob/master/eval/dataset/data.py"
    click DataPrep "https://github.com/dvlab-research/motcoder/blob/master/eval/dataset/prompts.py"
    click EvalHarness "https://github.com/dvlab-research/motcoder/blob/master/eval/eval.py"
    click Gen "https://github.com/dvlab-research/motcoder/blob/master/eval/vllm_gen.py"
    click Fix "https://github.com/dvlab-research/motcoder/blob/master/eval/vllm_fix.py"
    click EvalScripts "https://github.com/dvlab-research/motcoder/blob/master/eval/scripts/eval_motcoder_apps_codecontests.sh"
    click EvalScripts "https://github.com/dvlab-research/motcoder/blob/master/eval/scripts/eval_motcoder_reflection.sh"
    click Utils "https://github.com/dvlab-research/motcoder/blob/master/eval/testing_util.py"
    click Utils "https://github.com/dvlab-research/motcoder/blob/master/eval/utils.py"
    click GitIgnore "https://github.com/dvlab-research/motcoder/blob/master/.gitignore"
    click Readme "https://github.com/dvlab-research/motcoder/blob/master/Readme.md"
    click Images "https://github.com/dvlab-research/motcoder/tree/master/imgs/"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
