# deepseek-ai/deepseek-math architecture

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

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

## Overview

##### Project Type and Purpose
- DeepSeekMath is an open‐source research codebase for a large‐language model specialized in mathematical reasoning.
- It provides:
- Model inference scripts (Hugging Face & Replicate)
- A rich evaluation pipeline (few‐shot, zero‐shot, tool‐integrated)
- Data‐processing utilities and datasets for benchmarks

##### High‐Level Components
A. Model Artifacts & Interfaces
- “Hugging Face” and “Replicate” model endpoints
- Python scripts for text/chat completion (root + replicate/)
B. Evaluation Pipeline
- evaluation/configs: JSON configurations for few-shot/zero-shot setups
- evaluation/data_processing: ingestion, answer extraction, utility functions
- evaluation/datasets: collection of benchmark datasets (gsm8k, MATH, etc.)
- evaluation/few_shot_prompts: template definitions for chain-of-thought prompting
- evaluation/eval & evaluation/infer: core evaluation scripts (eval_script.py, run_cot_eval.py, run_pal_eval.py, run_tool_integrated_eval.py)
- evaluation/utils & environment.yml: shared utilities and reproducible environment spec
C. Results Aggregation & Visualization
- evaluation/summarize_results.py, evaluation/evaluation_results.json, evaluation/outputs.zip
D. External Services & Dependencies
- Hugging Face Transformers & GenerationConfig
- Replicate API (predict.py, predict_instruct.py)
- Python runtime managed via environment.yml

##### Interactions and Data Flows
1. Data Flow:
- Raw JSONL datasets → data_processing modules → formatted inputs
- Configs + formatted inputs + model interface → eval scripts
- eval scripts → generate outputs → evaluation_results.json
- summarize_results.py → aggregated metrics/plots
2. Inference Flow:
- User code (root quick-start) or replicate/predict.py → calls model API → returns completions
3. External Integrations:
- Hugging Face: model hosting & retrieval
- Replicate: alternative model serving endpoint

##### Architectural Patterns & Design Principles
- Modular separation: “data_processing” ↔ “eval” ↔ “summarize”
- Config-driven: interchangeable few-shot/zero-shot configurations
- Pluggable prompts: a directory of prompt definitions, easy to extend to new tasks
- Interface abstraction: common utils for invoking Hugging Face or Replicate

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        Datasets[(Evaluation Datasets)]:::data
        DataProc["Data Processing Module"]:::data
    end

    %% Evaluation Engine
    subgraph "Evaluation Engine"
        Configs["Evaluation Configurations"]:::eval
        Prompts["Few-Shot Prompt Templates"]:::eval
        EvalUtils["Evaluation Utilities"]:::eval
        EvalRunner["Evaluation Runner"]:::eval
        CotEval["CoT Eval Script"]:::eval
        PalEval["PAL Eval Script"]:::eval
        ToolEval["Tool-Integrated Eval Script"]:::eval
        SubmitJobs["Job Submission Script"]:::eval
        ParallelRuns["Parallel Runs Script"]:::eval
    end

    %% Model Interface Layer
    subgraph "Model Interface Layer"
        HF["Hugging Face Client"]:::external
        RepC["Replicate Predict"]:::external
        RepI["Replicate Predict Instruct"]:::external
    end

    %% Results Layer
    subgraph "Results Layer"
        Summarizer["Results Aggregator"]:::result
        ResultsFile[(evaluation_results.json)]:::result
    end

    %% Data Flow
    Datasets --> DataProc
    DataProc --> EvalRunner
    Configs --> EvalRunner
    Prompts --> EvalRunner
    EvalUtils --> EvalRunner
    EvalRunner --> HF
    EvalRunner --> RepC
    EvalRunner --> RepI
    HF --> EvalRunner
    RepC --> EvalRunner
    RepI --> EvalRunner
    EvalRunner --> Summarizer
    Summarizer --> ResultsFile

    %% Job Control Flow
    SubmitJobs --> EvalRunner
    ParallelRuns --> EvalRunner

    %% Click Events
    click DataProc "https://github.com/deepseek-ai/deepseek-math/tree/main/evaluation/data_processing"
    click Datasets "https://github.com/deepseek-ai/deepseek-math/tree/main/evaluation/datasets"
    click Configs "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/configs/few_shot_test_configs.json"
    click Configs "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/configs/zero_shot_test_configs.json"
    click Prompts "https://github.com/deepseek-ai/deepseek-math/tree/main/evaluation/few_shot_prompts"
    click EvalRunner "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/eval/eval_script.py"
    click EvalUtils "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/eval/utils.py"
    click EvalUtils "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/utils.py"
    click CotEval "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/infer/run_cot_eval.py"
    click PalEval "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/infer/run_pal_eval.py"
    click ToolEval "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/infer/run_tool_integrated_eval.py"
    click Summarizer "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/summarize_results.py"
    click ResultsFile "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/evaluation_results.json"
    click RepC "https://github.com/deepseek-ai/deepseek-math/blob/main/replicate/predict.py"
    click RepI "https://github.com/deepseek-ai/deepseek-math/blob/main/replicate/predict_instruct.py"
    click SubmitJobs "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/submit_eval_jobs.py"
    click ParallelRuns "https://github.com/deepseek-ai/deepseek-math/blob/main/evaluation/run_subset_parallel.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#000,stroke-width:1px
    classDef eval fill:#d4edda,stroke:#000,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#000,stroke-width:1px
    classDef result fill:#e2e3e5,stroke:#000,stroke-width:1px
```
