andimarafioti · andimarafioti · Jun 26, 2026 · Jun 26, 2026
diff --git a/.github/workflows/publish-hf-wheels.yml b/.github/workflows/publish-hf-wheels.yml
@@ -0,0 +1,206 @@
+name: Publish Hugging Face Wheels
+
+"on":
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      qwentts_ref:
+        description: qwentts.cpp commit, tag, or branch to build
+        required: true
+        default: 9dbe7ea26a01b30fccb117ae5e86807c1dc23d42
+      hf_repo_id:
+        description: Hugging Face dataset repo for wheel hosting
+        required: true
+        default: andimarafioti/qwentts-cpp-python-wheels
+
+permissions:
+  contents: read
+
+env:
+  HF_WHEEL_REPO_ID: ${{ inputs.hf_repo_id || vars.HF_WHEEL_REPO_ID || 'andimarafioti/qwentts-cpp-python-wheels' }}
+  QWENTTS_REF: ${{ inputs.qwentts_ref || '9dbe7ea26a01b30fccb117ae5e86807c1dc23d42' }}
+
+jobs:
+  build-wheels:
+    name: Linux ${{ matrix.arch }} CUDA ${{ matrix.cuda_version }} HF wheel
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x86_64
+            runner: ubuntu-22.04
+            cuda_repo_distro: ubuntu2204
+            cuda_repo_arch: x86_64
+            cuda_version: "12.4"
+            cuda_package_suffix: "12-4"
+            cuda_home: /usr/local/cuda-12.4
+            flavor: cu124
+            cuda_architectures: 75-virtual;80-real;86-real;90-real
+            manylinux_platform: manylinux_2_35_x86_64
+            build_jobs: "2"
+          - arch: aarch64
+            runner: ubuntu-22.04-arm
+            cuda_repo_distro: ubuntu2204
+            cuda_repo_arch: sbsa
+            cuda_version: "12.4"
+            cuda_package_suffix: "12-4"
+            cuda_home: /usr/local/cuda-12.4
+            flavor: cu124
+            cuda_architectures: 75-virtual;80-real;86-real;90-real
+            manylinux_platform: manylinux_2_35_aarch64
+            build_jobs: "2"
+          - arch: x86_64
+            runner: ubuntu-24.04
+            cuda_repo_distro: ubuntu2404
+            cuda_repo_arch: x86_64
+            cuda_version: "12.8"
+            cuda_package_suffix: "12-8"
+            cuda_home: /usr/local/cuda-12.8
+            flavor: cu128
+            cuda_architectures: 75-virtual;80-real;86-real;90-real;120-real;120-virtual
+            manylinux_platform: manylinux_2_39_x86_64
+            build_jobs: "2"
+          - arch: aarch64
+            runner: ubuntu-24.04-arm
+            cuda_repo_distro: ubuntu2404
+            cuda_repo_arch: sbsa
+            cuda_version: "12.8"
+            cuda_package_suffix: "12-8"
+            cuda_home: /usr/local/cuda-12.8
+            flavor: cu128
+            cuda_architectures: 75-virtual;80-real;86-real;90-real;120-real;120-virtual
+            manylinux_platform: manylinux_2_39_aarch64
+            build_jobs: "2"
+          - arch: x86_64
+            runner: ubuntu-24.04
+            cuda_repo_distro: ubuntu2404
+            cuda_repo_arch: x86_64
+            cuda_version: "13.0"
+            cuda_package_suffix: "13-0"
+            cuda_home: /usr/local/cuda-13.0
+            flavor: cu130
+            cuda_architectures: 75-virtual;80-real;86-real;90-real;121-real
+            manylinux_platform: manylinux_2_39_x86_64
+            build_jobs: "2"
+          - arch: aarch64
+            runner: ubuntu-24.04-arm
+            cuda_repo_distro: ubuntu2404
+            cuda_repo_arch: sbsa
+            cuda_version: "13.0"
+            cuda_package_suffix: "13-0"
+            cuda_home: /usr/local/cuda-13.0
+            flavor: cu130
+            cuda_architectures: 75-virtual;80-real;86-real;90-real;121-real
+            manylinux_platform: manylinux_2_39_aarch64
+            build_jobs: "2"
+    env:
+      QWENTTS_CPP_BACKEND: cuda
+      QWENTTS_CPP_BUILD_JOBS: ${{ matrix.build_jobs }}
+      CUDA_ARCHITECTURES: ${{ matrix.cuda_architectures }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Free disk space
+        run: |
+          sudo rm -rf /usr/local/lib/android /opt/ghc /usr/share/dotnet
+          sudo apt-get clean
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip auditwheel build wheel
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends cmake ninja-build patchelf wget ca-certificates
+
+      - name: Install CUDA toolkit
+        run: |
+          wget -q https://developer.download.nvidia.com/compute/cuda/repos/${{ matrix.cuda_repo_distro }}/${{ matrix.cuda_repo_arch }}/cuda-keyring_1.1-1_all.deb
+          sudo dpkg -i cuda-keyring_1.1-1_all.deb
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            cuda-nvcc-${{ matrix.cuda_package_suffix }} \
+            cuda-cudart-dev-${{ matrix.cuda_package_suffix }} \
+            libcublas-dev-${{ matrix.cuda_package_suffix }}
+          echo "${{ matrix.cuda_home }}/bin" >> "$GITHUB_PATH"
+          echo "CUDA_HOME=${{ matrix.cuda_home }}" >> "$GITHUB_ENV"
+          echo "CMAKE_CUDA_COMPILER=${{ matrix.cuda_home }}/bin/nvcc" >> "$GITHUB_ENV"
+
+      - name: Fetch qwentts.cpp
+        run: |
+          git clone --recursive https://github.com/ServeurpersoCom/qwentts.cpp third_party/qwentts.cpp
+          git -C third_party/qwentts.cpp checkout "$QWENTTS_REF"
+          git -C third_party/qwentts.cpp submodule update --init --recursive
+
+      - name: Build wheel
+        run: |
+          python scripts/set_local_version.py "${{ matrix.flavor }}"
+          python scripts/build_native.py \
+            --source third_party/qwentts.cpp \
+            --backend cuda \
+            --clean \
+            --cmake-arg=-G \
+            --cmake-arg=Ninja \
+            --cmake-arg="-DCMAKE_CUDA_ARCHITECTURES=$CUDA_ARCHITECTURES"
+          python -m build --wheel
+          mkdir -p wheelhouse
+          python -m auditwheel repair \
+            --plat ${{ matrix.manylinux_platform }} \
+            --exclude libcudart.so.12 \
+            --exclude libcudart.so.13 \
+            --exclude libcublas.so.12 \
+            --exclude libcublas.so.13 \
+            --exclude libcublasLt.so.12 \
+            --exclude libcublasLt.so.13 \
+            --exclude libcuda.so.1 \
+            -w wheelhouse \
+            dist/*.whl
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: hf-wheel-${{ matrix.flavor }}-${{ matrix.arch }}
+          path: wheelhouse/*.whl
+
+  publish-hf:
+    name: Publish HF wheel index
+    needs: build-wheels
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: hf-wheel-*
+          path: dist
+          merge-multiple: true
+
+      - name: Build wheel index
+        run: |
+          python -m pip install --upgrade pip huggingface-hub twine
+          python -m twine check --strict dist/*.whl
+          python scripts/prepare_hf_wheel_repo.py \
+            --dist dist \
+            --out hf-upload \
+            --repo-id "$HF_WHEEL_REPO_ID"
+
+      - name: Upload to Hugging Face
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          python scripts/upload_hf_wheels.py \
+            --folder hf-upload \
+            --repo-id "$HF_WHEEL_REPO_ID" \
+            --commit-message "Update qwentts-cpp-python wheels for ${GITHUB_REF_NAME}"
diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
@@ -26,41 +26,71 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          - arch: x86_64
+            runner: ubuntu-22.04
+            cuda_repo_distro: ubuntu2204
+            cuda_repo_arch: x86_64
+            cuda_version: "12.4"
+            cuda_package_suffix: "12-4"
+            cuda_home: /usr/local/cuda-12.4
+            wheel_build_tag: 1cu124
+            cuda_architectures: 75-virtual;80-real;86-real;90-real
+            manylinux_platform: manylinux_2_35_x86_64
+            build_jobs: "2"
+          - arch: aarch64
+            runner: ubuntu-22.04-arm
+            cuda_repo_distro: ubuntu2204
+            cuda_repo_arch: sbsa
+            cuda_version: "12.4"
+            cuda_package_suffix: "12-4"
+            cuda_home: /usr/local/cuda-12.4
+            wheel_build_tag: 1cu124
+            cuda_architectures: 75-virtual;80-real;86-real;90-real
+            manylinux_platform: manylinux_2_35_aarch64
+            build_jobs: "2"
           - arch: x86_64
             runner: ubuntu-24.04
+            cuda_repo_distro: ubuntu2404
             cuda_repo_arch: x86_64
             cuda_version: "12.8"
             cuda_package_suffix: "12-8"
             cuda_home: /usr/local/cuda-12.8
             wheel_build_tag: 1cu128
             cuda_architectures: 75-virtual;86-real;90-real;120-real;120-virtual
+            manylinux_platform: manylinux_2_39_x86_64
             build_jobs: "2"
           - arch: aarch64
             runner: ubuntu-24.04-arm
+            cuda_repo_distro: ubuntu2404
             cuda_repo_arch: sbsa
             cuda_version: "12.8"
             cuda_package_suffix: "12-8"
             cuda_home: /usr/local/cuda-12.8
             wheel_build_tag: 1cu128
             cuda_architectures: 75-virtual;86-real;90-real;120-real;120-virtual
+            manylinux_platform: manylinux_2_39_aarch64
             build_jobs: "2"
           - arch: x86_64
             runner: ubuntu-24.04
+            cuda_repo_distro: ubuntu2404
             cuda_repo_arch: x86_64
             cuda_version: "13.0"
             cuda_package_suffix: "13-0"
             cuda_home: /usr/local/cuda-13.0
             wheel_build_tag: 1cu130
             cuda_architectures: 75-virtual;80-real;86-real;90-real;121-real
+            manylinux_platform: manylinux_2_39_x86_64
             build_jobs: "2"
           - arch: aarch64
             runner: ubuntu-24.04-arm
+            cuda_repo_distro: ubuntu2404
             cuda_repo_arch: sbsa
             cuda_version: "13.0"
             cuda_package_suffix: "13-0"
             cuda_home: /usr/local/cuda-13.0
             wheel_build_tag: 1cu130
             cuda_architectures: 75-virtual;80-real;86-real;90-real;121-real
+            manylinux_platform: manylinux_2_39_aarch64
             build_jobs: "2"
     env:
       QWENTTS_CPP_BACKEND: cuda
@@ -88,7 +118,7 @@ jobs:
 
       - name: Install CUDA toolkit
         run: |
-          wget -q https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/${{ matrix.cuda_repo_arch }}/cuda-keyring_1.1-1_all.deb
+          wget -q https://developer.download.nvidia.com/compute/cuda/repos/${{ matrix.cuda_repo_distro }}/${{ matrix.cuda_repo_arch }}/cuda-keyring_1.1-1_all.deb
           sudo dpkg -i cuda-keyring_1.1-1_all.deb
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends \
@@ -117,7 +147,7 @@ jobs:
           python -m build --wheel
           mkdir -p wheelhouse
           python -m auditwheel repair \
-            --plat manylinux_2_39_${{ matrix.arch }} \
+            --plat ${{ matrix.manylinux_platform }} \
             --exclude libcudart.so.12 \
             --exclude libcudart.so.13 \
             --exclude libcublas.so.12 \

diff --git a/AGENTS.md b/AGENTS.md
@@ -20,6 +20,13 @@ The PR wheel workflow may still build CPU and CUDA 13 wheels as downloadable
 validation artifacts. Those artifacts are not uploaded to PyPI by the publish
 workflow.
 
+Additional CUDA wheels can be published to Hugging Face Hub by
+`.github/workflows/publish-hf-wheels.yml`. That workflow builds local-version
+variants such as `0.2.0+cu124`, `0.2.0+cu128`, and `0.2.0+cu130`, prepares
+static `--find-links` pages, creates the public dataset repo if needed, and
+uploads the wheel index using the `HF_TOKEN` repository secret. Do not upload
+those local-version CUDA variants to PyPI.
+
 CUDA release wheels keep native cubins for sm_86, sm_90, and sm_120, plus PTX
 fallbacks for sm_75 and the newest supported CUDA architecture. This keeps the
 public CUDA 12.8 wheels under PyPI's default per-file upload limit while

diff --git a/README.md b/README.md
@@ -33,6 +33,35 @@ QWENTTS_CPP_WHEEL_BUILD_TAG=1cpu python -m build --wheel
 package. CPU builds are still useful for development and smoke tests, but they
 are not the primary release target.
 
+## Installation
+
+The default PyPI package is built for CUDA 12.8:
+
+```bash
+pip install qwentts-cpp-python
+```
+
+Additional CUDA wheels are published to Hugging Face Hub as local-version
+variants. Use them when the PyPI CUDA 12.8 wheel does not match the runtime or
+GPU target, for example DGX Spark / GB10 with CUDA 13:
+
+```bash
+pip install "qwentts-cpp-python==0.2.0+cu124" \
+  -f https://huggingface.co/datasets/andimarafioti/qwentts-cpp-python-wheels/resolve/main/whl/cu124.html
+
+pip install "qwentts-cpp-python==0.2.0+cu128" \
+  -f https://huggingface.co/datasets/andimarafioti/qwentts-cpp-python-wheels/resolve/main/whl/cu128.html
+
+pip install "qwentts-cpp-python==0.2.0+cu130" \
+  -f https://huggingface.co/datasets/andimarafioti/qwentts-cpp-python-wheels/resolve/main/whl/cu130.html
+```
+
+Hugging Face raw file hosting does not expose a PyTorch-style package directory
+index, so these commands use pip's `--find-links` mode. Dependencies still
+resolve from PyPI normally. The wheels do not bundle CUDA runtime or cuBLAS
+libraries; use a base image or system installation that provides the matching
+CUDA runtime.
+
 The CI wheel build defaults to qwentts.cpp
 `9dbe7ea26a01b30fccb117ae5e86807c1dc23d42`, which includes the scheduler
 resets and ABI v2 cached voice-reference fields. CPU and CUDA both stay on the