rasbt/LLMs-from-scratch

name: Test latest PyTorch-compatible Python version
on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'    # Run workflow for changes in Python files
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - name: Set up Python
      uses: actions/setup-python@v6
      with:
        python-version: "3.13"

    - name: Install dependencies
      run: |
        curl -LsSf https://astral.sh/uv/install.sh | sh
        uv sync --dev --python=3.13
        uv add pytest-ruff nbval

    - name: Test Selected Python Scripts
      run: |
        source .venv/bin/activate
        pytest setup/02_installing-python-libraries/tests.py
        pytest ch04/01_main-chapter-code/tests.py
        pytest ch05/01_main-chapter-code/tests.py
        pytest ch06/01_main-chapter-code/tests.py

    - name: Validate Selected Jupyter Notebooks
      run: |
        source .venv/bin/activate
        pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
        pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
        pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

name: Code tests Linux

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  uv-tests:
    name: Code tests (Linux)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python (uv)
        uses: actions/setup-python@v6
        with:
          python-version: "3.13"

      - name: Install uv and dependencies
        shell: bash
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          uv sync --dev  # tests for backwards compatibility
          uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
          uv add pytest-ruff nbval

      - name: Test Selected Python Scripts (uv)
        shell: bash
        run: |
          source .venv/bin/activate
          pytest setup/02_installing-python-libraries/tests.py
          pytest ch03/02_bonus_efficient-multihead-attention/tests/test_mha_implementations.py
          pytest ch04/01_main-chapter-code/tests.py
          pytest ch04/03_kv-cache/tests.py
          pytest ch05/01_main-chapter-code/tests.py
          pytest ch05/07_gpt_to_llama/tests/tests_rope_and_parts.py
          pytest ch05/07_gpt_to_llama/tests/test_llama32_nb.py
          pytest ch05/11_qwen3/tests/test_qwen3_nb.py
          pytest ch05/12_gemma3/tests/test_gemma3_nb.py
          pytest ch05/12_gemma3/tests/test_gemma3_kv_nb.py
          pytest ch05/13_olmo3/tests/test_olmo3_nb.py
          pytest ch05/13_olmo3/tests/test_olmo3_kvcache_nb.py
          pytest ch06/01_main-chapter-code/tests.py

      - name: Validate Selected Jupyter Notebooks (uv)
        shell: bash
        run: |
          source .venv/bin/activate
          pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
          pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

      - name: Test Selected Bonus Materials
        shell: bash
        run: |
          source .venv/bin/activate
          pytest ch02/05_bpe-from-scratch/tests.py

      - name: Test Selected Bonus Materials
        shell: bash
        run: |
          source .venv/bin/activate
          pytest pkg/llms_from_scratch/tests/

name: Code tests macOS

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  uv-tests:
    name: Code tests (macOS)
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python (uv)
        uses: actions/setup-python@v6
        with:
          python-version: "3.13"

      - name: Install uv and dependencies
        shell: bash
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          uv sync --dev --python=3.10  # tests for backwards compatibility
          uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
          uv add pytest-ruff nbval

      - name: Test Selected Python Scripts (uv)
        shell: bash
        run: |
          source .venv/bin/activate
          pytest setup/02_installing-python-libraries/tests.py
          pytest ch04/01_main-chapter-code/tests.py
          pytest ch05/01_main-chapter-code/tests.py
          pytest ch05/07_gpt_to_llama/tests/tests_rope_and_parts.py
          pytest ch05/07_gpt_to_llama/tests/test_llama32_nb.py
          pytest ch05/11_qwen3/tests/test_qwen3_nb.py
          pytest ch05/12_gemma3/tests/test_gemma3_nb.py
          pytest ch05/12_gemma3/tests/test_gemma3_kv_nb.py
          pytest ch06/01_main-chapter-code/tests.py

      - name: Validate Selected Jupyter Notebooks (uv)
        shell: bash
        run: |
          source .venv/bin/activate
          pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
          pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

name: Test PyTorch 2.3 and 2.5

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'    # Run workflow for changes in Python files
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        pytorch-version: [ 2.3.0, 2.5.0 ]

    steps:
    - uses: actions/checkout@v6

    - name: Set up Python
      uses: actions/setup-python@v6
      with:
        python-version: "3.13"

    - name: Install dependencies
      run: |
        curl -LsSf https://astral.sh/uv/install.sh | sh
        uv sync --dev --python=3.10  # tests for backwards compatibility
        uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
        uv pip install torch==${{ matrix.pytorch-version }} pytest-ruff nbval

    - name: Test Selected Python Scripts
      run: |
        source .venv/bin/activate
        pytest setup/02_installing-python-libraries/tests.py
        pytest ch04/01_main-chapter-code/tests.py
        pytest ch05/01_main-chapter-code/tests.py
        pytest ch06/01_main-chapter-code/tests.py

    - name: Validate Selected Jupyter Notebooks
      run: |
        source .venv/bin/activate
        pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
        pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
        pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

name: Code tests (plain pip)

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  pip-tests:
    name: Pip Tests (Ubuntu Only)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.10"  # tests for backwards compatibility

      - name: Create Virtual Environment and Install Dependencies
        run: |
          python -m venv .venv
          source .venv/bin/activate
          pip install --upgrade pip
          # Necessary because there is not much storage space on this runner:
          pip install torch==2.9.1+cpu --index-url https://download.pytorch.org/whl/cpu
          pip install -r requirements.txt --no-deps
          pip install jupyterlab pandas tensorflow matplotlib
          pip install pytest pytest-ruff nbval

      - name: Test Selected Python Scripts
        run: |
          source .venv/bin/activate
          pytest setup/02_installing-python-libraries/tests.py
          pytest ch04/01_main-chapter-code/tests.py
          pytest ch05/01_main-chapter-code/tests.py
          pytest ch06/01_main-chapter-code/tests.py

      - name: Validate Selected Jupyter Notebooks
        run: |
          source .venv/bin/activate
          pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
          pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

name: Code tests (pixi)

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]

    steps:
      - uses: actions/checkout@v6

      - name: Set up pixi (without caching)
        uses: prefix-dev/setup-pixi@0f64e482e3d251f735019b1bc7fb0413ead75b2c # v0.8.2
        with:
          environments: tests
          cache: false

      - name: List installed packages
        run: |
          pixi list --environment tests
          pixi run --environment tests pip install "huggingface-hub>=0.30.0,<1.0"

      - name: Test Selected Python Scripts
        shell: pixi run --environment tests bash -e {0}
        run: |
          pytest setup/02_installing-python-libraries/tests.py
          pytest ch04/01_main-chapter-code/tests.py
          pytest ch05/01_main-chapter-code/tests.py
          pytest ch06/01_main-chapter-code/tests.py

      - name: Validate Selected Jupyter Notebooks
        shell: pixi run --environment tests bash -e {0}
        run: |
          pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
          pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

name: Test latest PyTorch nightly / release candidate
on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'    # Run workflow for changes in Python files
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - name: Set up Python
      uses: actions/setup-python@v6
      with:
        python-version: "3.13"

    - name: Install dependencies
      run: |
        curl -LsSf https://astral.sh/uv/install.sh | sh
        uv sync --dev  # tests for backwards compatibility
        uv add pytest-ruff nbval
        uv pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cpu

    - name: Test Selected Python Scripts
      run: |
        source .venv/bin/activate
        pytest setup/02_installing-python-libraries/tests.py
        pytest ch04/01_main-chapter-code/tests.py
        pytest ch05/01_main-chapter-code/tests.py
        pytest ch06/01_main-chapter-code/tests.py

    - name: Validate Selected Jupyter Notebooks
      run: |
        source .venv/bin/activate
        pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
        pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
        pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

name: Code tests Windows (uv/pip)

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.py'
      - '**/*.ipynb'
      - '**/*.yaml'
      - '**/*.yml'
      - '**/*.sh'

jobs:
  test:
    runs-on: windows-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

      - name: Install dependencies
        shell: bash
        run: |
          export PATH="$HOME/.local/bin:$PATH"
          python -m pip install --upgrade pip
          pip install uv
          uv venv --python=python3.11
          source .venv/Scripts/activate
          pip install -r requirements.txt  # because of dependency issue on Windows when using `uv pip`
          pip install tensorflow-io-gcs-filesystem==0.31.0  # Explicit for Windows
          pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
          pip install pytest-ruff nbval
          pip install -e .

      - name: Run Python Tests
        shell: bash
        run: |
          source .venv/Scripts/activate
          pytest setup/02_installing-python-libraries/tests.py
          pytest ch04/01_main-chapter-code/tests.py
          pytest ch05/01_main-chapter-code/tests.py
          pytest ch05/07_gpt_to_llama/tests/tests_rope_and_parts.py
          pytest ch05/07_gpt_to_llama/tests/test_llama32_nb.py
          pytest ch05/11_qwen3/tests/test_qwen3_nb.py
          pytest ch06/01_main-chapter-code/tests.py

      - name: Run Jupyter Notebook Tests
        shell: bash
        run: |
          source .venv/Scripts/activate
          pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
          pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

name: Check hyperlinks

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v6

    - name: Set up Python
      uses: actions/setup-python@v6
      with:
        python-version: "3.10"

    - name: Install dependencies
      run: |
        curl -LsSf https://astral.sh/uv/install.sh | sh
        uv sync --dev
        uv add pytest-check-links

    - name: Check links
      env:
        CHECK_LINKS_TIMEOUT: "10"
      run: |
        source .venv/bin/activate
        pytest --check-links ./ \
          --check-links-ignore "https://platform.openai.com/*" \
          --check-links-ignore "https://openai.com/*" \
          --check-links-ignore "https://arena.lmsys.org" \
          --check-links-ignore "https?://localhost(:\\d+)?/.*" \
          --check-links-ignore "https?://127[.]0[.]0[.]1(:\\d+)?/.*" \
          --check-links-ignore "https://mng\\.bz/.*" \
          --check-links-ignore "https://github\\.com/.*" \
          --check-links-ignore "https://unsloth.ai/blog/gradient" \
          --check-links-ignore "https://www.reddit.com/r/*" \
          --check-links-ignore "https://code.visualstudio.com/*" \
          --check-links-ignore "https://arxiv.org/*" \
          --check-links-ignore "https://ai.stanford.edu/~amaas/data/sentiment/" \
          --check-links-ignore "https://x.com/*" \
          --check-links-ignore "https://scholar.google.com/*"

name: Spell Check

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  spellcheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.10"

      - name: Install codespell
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          uv sync --dev --python=3.10
          uv add codespell

      - name: Run codespell
        run: |
          source .venv/bin/activate
          codespell -L "ocassion,occassion,ot,te,tje" **/*.{txt,md,py,ipynb}

name: PEP8 Style checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  flake8:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - name: Set up Python
      uses: actions/setup-python@v6
      with:
        python-version: "3.13"
    - name: Install ruff (a faster flake 8 equivalent)
      run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          uv sync --dev --python=3.10
          uv add ruff

    - name: Run ruff with exceptions
      run: |
        source .venv/bin/activate
        ruff check .