# internlm/internlm-math architecture

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

- Interactive diagram: https://gitdiagram.com/internlm/internlm-math
- Repository: https://github.com/internlm/internlm-math

## Overview

Step 1: Identify the Project Type and Purpose
- This is an open-source toolkit/repository for state-of-the-art bilingual math reasoning Large Language Models (LLMs).
- It bundles:
- Pretrained and fine-tuned InternLM2-Math models (solver, prover, verifier, augmentor)
- Datasets and proof benchmarks (Lean-Github, Lean-Workbook, MiniF2F)
- Inference “agent” code for tool-augmented reasoning and code interpretation
- Example scripts for HuggingFace and LMDeploy pipelines
- Evaluation scripts and metrics computation

Step 2: Analyze the File Structure
- Top-level: README.md, LICENSE, .gitignore
- agent/: Python code (math_agent.py) + requirements for tool-calling inference
- assets/: images and logos used in documentation
- examples/: lightweight inference demos (HuggingFace & LMDeploy)
- lean-github/: dataset compilation for Lean-GitHub proofs
- leanworkbook/: Lean-Workbook data, Lean header file, inference scripts (backtranslate, NLI, translate)
- minif2f/: MiniF2F dataset, proof-search Python scripts, eval scripts, shell wrappers, requirements

Step 3: Extract Insights from README
- Project layers:
1. Data Preparation (Lean-Github, Lean-Workbook, MiniF2F)
2. Model Checkpoints & Trainer (InternLM2-Math base & SFT)
3. Inference Agent (tool-calling via Python “agent”)
4. Evaluation & Metrics (compute_metrics.py, OpenCompass integration)
5. Deployment Examples (LMDeploy, HuggingFace transformers)
- Key technologies: Python, Lean 3/4, LLM frameworks (Turbomind, Transformers), JSONL datasets, shell scripting

Step 4: Main Components and Their Interactions
##### Data Layer
- Datasets in JSONL format (minif2f/data, lean-github source, leanworkbook/header.lean)
- Data-prep scripts (minif2f/proofsearch_*.py, lean-github README instructions)
##### Model Layer
- Pretrain & SFT checkpoints (InternLM2-Math-Base-7B/20B, InternLM2-Math-7B/20B)
- Training code lives outside this repo (referenced in InternLM core)
##### Inference Layer (agent)
- math_agent.py orchestrates prompt → model → tool (e.g., Python interpreter, Lean) → back to model
- Example pipelines: LMDeploy (TurbomindEngineConfig) and HuggingFace ChatTemplateConfig
##### Evaluation Layer
- compute_metrics.py for MiniF2F
- Shell scripts under minif2f/scripts for large-scale eval runs
- OpenCompass config for GSM8K/MATH benchmarks
##### External Services
- HuggingFace Hub (model & dataset storage)
- ModelScope, OpenXLab, LMDeploy for deployment
- ArXiv, paper links, technical reports

Step 5: Architectural Patterns and Design Principles
- Modular monorepo: clear separation of datasets, inference, examples, evaluation
- Pipeline pattern in “agent”: data in → preprocess → LLM call → tool call → postprocess → output
- Layered architecture: Data → Model → Inference Agent → Evaluation/Deployment
- Extensibility: add new datasets or inference tools by dropping modules into dedicated folders

- Core LLM engine surrounded by:
- Data modules feeding training/eval
- Inference agent orchestrating external tool calls
- Example scripts showing two deployment pathways (LMDeploy vs HF)
- That evaluation is pluggable (shell scripts, compute_metrics, OpenCompass)

Step 7: Diagramming Guidelines
- Datasets → Model (training/eval)
- Model ↔ Agent (inference requests & responses)
- Agent → External Tools (Python Interpreter, Lean) → Agent → User
- Evaluation scripts → Metrics → Reports
- Blue for Data modules
- Green for Model checkpoints
- Orange for Inference Agent and tool integration
- Purple for Examples/Deployment scripts
- Gray for External services (HuggingFace, ModelScope, OpenXLab)

Step 8: Call to Action for the Principal Software Engineer
- Drill down into each zone with sub-components (folders, scripts, datasets)
- Non-obvious integrations (e.g., how math_agent.py invokes Lean tactics or Python code)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        LG["Lean-GitHub Dataset"]:::data
        subgraph "Lean-Workbook"
            direction TB
            LW1["header.lean"]:::data
            LW2["inference_backtranslate.py"]:::data
            LW3["inference_nli.py"]:::data
            LW4["inference_translate_answer.py"]:::data
        end
        subgraph "MiniF2F"
            direction TB
            MF1["minif2f-lean4.7.0.jsonl"]:::data
            MF2["minif2f.jsonl"]:::data
            PS1["proofsearch_internLM2.py"]:::data
            PS2["proofsearch_internLM2-StepProver.py"]:::data
            PS3["proofsearch_internLM2.5-StepProver.py"]:::data
            PS4["proofsearch_internLM2-plus.py"]:::data
        end
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        IM["InternLM2-Math Model (Base & SFT)"]:::model
    end

    %% Inference Layer
    subgraph "Inference Layer"
        direction TB
        MA["math_agent.py"]:::agent
        REQ["requirements.txt"]:::agent
        ARM["agent README"]:::agent
        subgraph "External Tools"
            direction TB
            PY["Python Interpreter"]:::tool
            LE["Lean 3/4"]:::tool
        end
    end

    %% Evaluation Layer
    subgraph "Evaluation Layer"
        direction TB
        CM["compute_metrics.py"]:::eval
        subgraph "Eval Scripts"
            direction TB
            ES1["eval_internLM2_7b.sh"]:::eval
            ES2["eval_internLM2_20b.sh"]:::eval
            ES3["eval_internLM2-plus_7b.sh"]:::eval
            ES4["eval_internLM2-plus_20b.sh"]:::eval
            ES5["eval_internLM2-step-prover.sh"]:::eval
        end
        RPT["Metrics Reports"]:::eval
    end

    %% Deployment & External Services
    subgraph "Deployment & External"
        direction TB
        EX1["inference_huggingface.py"]:::deploy
        EX2["inference_lmdeploy.py"]:::deploy
        subgraph "Services"
            direction TB
            HF["HuggingFace Hub"]:::external
            MS["ModelScope"]:::external
            OX["OpenXLab / LMDeploy"]:::external
        end
    end

    %% Connections
    LG --> IM
    LW1 --> IM
    LW2 --> IM
    LW3 --> IM
    LW4 --> IM
    MF1 --> IM
    MF2 --> IM
    PS1 --> IM
    PS2 --> IM
    PS3 --> IM
    PS4 --> IM

    IM <--> MA
    MA --> PY
    MA --> LE

    MA --> EX1
    MA --> EX2

    CM --> RPT
    ES1 --> RPT
    ES2 --> RPT
    ES3 --> RPT
    ES4 --> RPT
    ES5 --> RPT

    IM --> HF
    IM --> MS
    EX2 --> OX

    %% Click Events
    click LG "https://github.com/internlm/internlm-math/tree/main/lean-github/"
    click LW1 "https://github.com/internlm/internlm-math/blob/main/leanworkbook/header.lean"
    click LW2 "https://github.com/internlm/internlm-math/blob/main/leanworkbook/inference_backtranslate.py"
    click LW3 "https://github.com/internlm/internlm-math/blob/main/leanworkbook/inference_nli.py"
    click LW4 "https://github.com/internlm/internlm-math/blob/main/leanworkbook/inference_translate_answer.py"
    click MF1 "https://github.com/internlm/internlm-math/blob/main/minif2f/data/minif2f-lean4.7.0.jsonl"
    click MF2 "https://github.com/internlm/internlm-math/blob/main/minif2f/data/minif2f.jsonl"
    click PS1 "https://github.com/internlm/internlm-math/blob/main/minif2f/proofsearch_internLM2.py"
    click PS2 "https://github.com/internlm/internlm-math/blob/main/minif2f/proofsearch_internLM2-StepProver.py"
    click PS3 "https://github.com/internlm/internlm-math/blob/main/minif2f/proofsearch_internLM2.5-StepProver.py"
    click PS4 "https://github.com/internlm/internlm-math/blob/main/minif2f/proofsearch_internLM2-plus.py"
    click MA "https://github.com/internlm/internlm-math/blob/main/agent/math_agent.py"
    click REQ "https://github.com/internlm/internlm-math/blob/main/agent/requirements.txt"
    click ARM "https://github.com/internlm/internlm-math/blob/main/agent/README.md"
    click CM "https://github.com/internlm/internlm-math/blob/main/minif2f/compute_metrics.py"
    click ES1 "https://github.com/internlm/internlm-math/blob/main/minif2f/scripts/eval_internLM2_7b.sh"
    click ES2 "https://github.com/internlm/internlm-math/blob/main/minif2f/scripts/eval_internLM2_20b.sh"
    click ES3 "https://github.com/internlm/internlm-math/blob/main/minif2f/scripts/eval_internLM2-plus_7b.sh"
    click ES4 "https://github.com/internlm/internlm-math/blob/main/minif2f/scripts/eval_internLM2-plus_20b.sh"
    click ES5 "https://github.com/internlm/internlm-math/blob/main/minif2f/scripts/eval_internLM2-step-prover.sh"
    click EX1 "https://github.com/internlm/internlm-math/blob/main/examples/inference_huggingface.py"
    click EX2 "https://github.com/internlm/internlm-math/blob/main/examples/inference_lmdeploy.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#66b0ff,color:#004085
    classDef model fill:#d4edda,stroke:#8fd19e,color:#155724
    classDef agent fill:#fff3cd,stroke:#ffe08a,color:#856404
    classDef tool fill:#ffe5b4,stroke:#ffcc80,color:#8b4513
    classDef eval fill:#e2e3e5,stroke:#b8b9ba,color:#383d41
    classDef deploy fill:#f5e6ff,stroke:#d4b3ff,color:#4f026f
    classDef external fill:#e2e3e5,stroke:#b8b9ba,color:#383d41
```
