ggml-python 0.0.39__tar.gz → 0.0.40__tar.gz

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/lint.yaml

@@ -12,10 +12,10 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/publish.yaml

@@ -2,7 +2,12 @@ name: Publish
 
 # Based on: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
 
-on: workflow_dispatch
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*.*.*"
+      - "!v*.*.*-*"
 
 jobs:
   build-n-publish:
@@ -10,11 +15,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         submodules: "true"
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: "3.8"
     - name: Install dependencies
@@ -25,8 +30,6 @@ jobs:
       run: |
         python3 -m build --sdist
     - name: Publish distribution to PyPI
-      # TODO: move to tag based releases
-      # if: startsWith(github.ref, 'refs/tags')
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
         password: ${{ secrets.PYPI_API_TOKEN }}

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/test.yaml

@@ -16,11 +16,11 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -38,6 +38,32 @@ jobs:
         run: |
           python -m pytest -s -vvvv
 
+  build-linux-onnx:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip pytest cmake scikit-build setuptools
+          python3 -m pip install \
+            --verbose \
+            --config-settings cmake.args='-DCMAKE_BUILD_TYPE=Debug;-DCMAKE_CXX_FLAGS=-g3;-DCMAKE_C_FLAGS=-g3' \
+            --config-settings cmake.verbose=true \
+            --config-settings logging.level=INFO \
+            --config-settings install.strip=false \
+            --editable ".[test,onnx,onnx-tests]"
+      - name: Test ONNX backend
+        run: |
+          python -m pytest -s -vvvv tests/test_ggml_onnx.py
+
   build-windows:
     runs-on: windows-latest
     strategy:
@@ -45,11 +71,11 @@ jobs:
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -69,11 +95,11 @@ jobs:
         python-version: ["3.9", "3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
@@ -99,11 +125,11 @@ jobs:
   build-macos-intel:
     runs-on: macos-15-intel
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
       - name: Set up Python 3.9
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.9"
           cache: "pip"
@@ -130,11 +156,11 @@ jobs:
     runs-on: macos-15
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.9"
           cache: "pip"

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/wheels-cuda.yaml

@@ -1,6 +1,11 @@
 name: Wheels CUDA
 
-on: workflow_dispatch
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*.*.*"
+      - "!v*.*.*-*"
 
 permissions:
   contents: write
@@ -63,17 +68,17 @@ jobs:
         with:
           arch: x64
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.pyver }}
           cache: "pip"
 
       - name: Setup Mamba
-        uses: conda-incubator/setup-miniconda@v3.1.0
+        uses: conda-incubator/setup-miniconda@v4.0.1
         with:
           activate-environment: "ggml"
           python-version: ${{ matrix.pyver }}
@@ -224,7 +229,7 @@ jobs:
           # Publish tags that reflect the actual installed toolkit version.
           Write-Output "CUDA_VERSION=$cudaTagVersion" >> $env:GITHUB_ENV
 
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@v3
         if: startsWith(github.ref, 'refs/tags/')
         with:
           files: dist/*

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/wheels-index.yaml

@@ -1,9 +1,11 @@
 name: Wheels Index
 
 on:
-  # Trigger on any new release
-  release:
-    types: [published]
+  # Trigger when release-asset workflows complete.
+  workflow_run:
+    workflows: ["Publish", "Wheels", "Wheels CUDA", "Wheels Metal", "Wheels Vulkan", "Wheels ROCm"]
+    types:
+      - completed
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -29,11 +31,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v6
       - name: Build
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
+          ./scripts/get-releases.sh
           ./scripts/releases-to-pep-503.sh index/whl/cpu '^[v]?[0-9]+\.[0-9]+\.[0-9]+$'
           ./scripts/releases-to-pep-503.sh index/whl/cu118 '^[v]?[0-9]+\.[0-9]+\.[0-9]+-cu118$'
           ./scripts/releases-to-pep-503.sh index/whl/cu121 '^[v]?[0-9]+\.[0-9]+\.[0-9]+-cu121$'
@@ -48,10 +53,10 @@ jobs:
           ./scripts/releases-to-pep-503.sh index/whl/hip-radeon '^[v]?[0-9]+\.[0-9]+\.[0-9]+-hip-radeon$'
           ./scripts/releases-to-pep-503.sh index/whl/metal '^[v]?[0-9]+\.[0-9]+\.[0-9]+-metal$'
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           # Upload entire repository
-          path: "index"
+          path: 'index'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/wheels-metal.yaml

@@ -1,6 +1,11 @@
 name: Wheels Metal
 
-on: workflow_dispatch
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*.*.*"
+      - "!v*.*.*-*"
 
 permissions:
   contents: write
@@ -14,18 +19,18 @@ jobs:
         os: [macos-14, macos-15]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
 
       # Used to host cibuildwheel.
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
           cache: "pip"
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.22.0
+        uses: pypa/cibuildwheel@v3.4.1
         env:
           CIBW_REPAIR_WHEEL_COMMAND: ""
           CIBW_ARCHS: "arm64"
@@ -37,7 +42,7 @@ jobs:
           package-dir: .
           output-dir: wheelhouse
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: wheels-mac_${{ matrix.os }}
           path: ./wheelhouse/*.whl
@@ -49,12 +54,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           merge-multiple: true
           path: dist
 
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@v3
         with:
           files: dist/*
           # Set release name to <tag>-metal.

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/wheels-rocm.yaml

@@ -13,7 +13,8 @@ on:
         default: gfx1150;gfx1151;gfx1200;gfx1201;gfx1100;gfx1101;gfx1102;gfx1030;gfx1031;gfx1032
   push:
     tags:
-      - "v*"
+      - "v*.*.*"
+      - "!v*.*.*-*"
 
 permissions:
   contents: write
@@ -38,11 +39,11 @@ jobs:
           apt-get update
           apt-get install -y --no-install-recommends git cmake lsb-release ninja-build
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.pyver }}
 
@@ -75,12 +76,12 @@ jobs:
           export CMAKE_ARGS="-DGGML_HIP=on -DGGML_NATIVE=off -DGGML_AVX=off -DGGML_AVX2=off -DGGML_FMA=off -DGGML_F16C=off -DAMDGPU_TARGETS=$amdgpu_targets -DCMAKE_HIP_ARCHITECTURES=$amdgpu_targets"
           python -m build --wheel
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: wheels-rocm${{ env.ROCM_VERSION }}-${{ matrix.os }}
           path: dist/*.whl
 
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@v3
         if: startsWith(github.ref, 'refs/tags/')
         with:
           files: dist/*
@@ -102,11 +103,11 @@ jobs:
             amdgpu_targets: gfx1150;gfx1151;gfx1200;gfx1201;gfx1100;gfx1101;gfx1102;gfx1030;gfx1031;gfx1032
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.pyver }}
           cache: "pip"
@@ -119,7 +120,7 @@ jobs:
 
       - name: Cache ROCm installation
         id: cache-rocm
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: C:\Program Files\AMD\ROCm
           key: cache-gha-rocm-${{ env.HIPSDK_INSTALLER_VERSION }}-${{ runner.os }}
@@ -134,9 +135,9 @@ jobs:
             -OutFile "${env:RUNNER_TEMP}\rocm-install.exe"
           Write-Host "Installing AMD HIP SDK"
           $proc = Start-Process "${env:RUNNER_TEMP}\rocm-install.exe" -ArgumentList '-install' -NoNewWindow -PassThru
-          $completed = $proc.WaitForExit(600000)
+          $completed = $proc.WaitForExit(1800000)
           if (-not $completed) {
-            Write-Error "ROCm installation timed out after 10 minutes"
+            Write-Error "ROCm installation timed out after 30 minutes"
             $proc.Kill()
             exit 1
           }
@@ -212,12 +213,12 @@ jobs:
           Remove-Item dist\*.whl
           python -m wheel pack $wheelRoot.FullName -d dist
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: wheels-hip-${{ matrix.name }}-windows-2022
           path: dist/*.whl
 
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@v3
         if: startsWith(github.ref, 'refs/tags/')
         with:
           files: dist/*

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/wheels-vulkan.yaml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - "v*.*.*"
+      - "!v*.*.*-*"
   workflow_dispatch:
 
 permissions:
@@ -35,11 +36,11 @@ jobs:
         with:
           arch: x64
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.pyver }}
           cache: "pip"
@@ -101,7 +102,7 @@ jobs:
           New-Item -ItemType Directory -Force wheelhouse | Out-Null
           Copy-Item dist/*.whl wheelhouse/
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: ${{ matrix.artifact }}
           path: ./wheelhouse/*.whl
@@ -113,12 +114,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           merge-multiple: true
           path: dist
 
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@v3
         with:
           files: dist/*
           # Set release name to <tag>-vulkan.

{ggml_python-0.0.39 → ggml_python-0.0.40}/.github/workflows/wheels.yaml

@@ -1,6 +1,11 @@
 name: Wheels
 
-on: workflow_dispatch
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*.*.*"
+      - "!v*.*.*-*"
 
 permissions:
   contents: write
@@ -14,23 +19,26 @@ jobs:
         os: [ubuntu-22.04, windows-2022, macos-14, macos-15]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
 
       # Used to host cibuildwheel.
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.9"
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.22.0
+        uses: pypa/cibuildwheel@v3.4.1
         env:
           # Keep repair disabled by default for non-Linux platforms in this job.
           CIBW_REPAIR_WHEEL_COMMAND: ""
           # Linux needs auditwheel repair so manylinux and musllinux wheels are
           # published with distinct platform tags instead of generic linux tags.
           CIBW_REPAIR_WHEEL_COMMAND_LINUX: "LD_LIBRARY_PATH=/project/ggml/lib auditwheel repair -w {dest_dir} {wheel}"
+          # cibuildwheel v3 defaults to manylinux_2_28 images whose current
+          # GCC toolchain emits symbols newer than the policy allows.
+          CIBW_MANYLINUX_X86_64_IMAGE: "manylinux2014"
           # The release wheel is tagged py3-none, so one build per platform
           # covers all supported Python versions and avoids duplicate names.
           CIBW_BUILD_LINUX: "cp38-*"
@@ -47,7 +55,7 @@ jobs:
           package-dir: .
           output-dir: wheelhouse
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: wheels-${{ matrix.os }}
           path: ./wheelhouse/*.whl
@@ -56,16 +64,18 @@ jobs:
     name: Build arm64 wheels
     runs-on: ubuntu-24.04-arm
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           submodules: "recursive"
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.22.0
+        uses: pypa/cibuildwheel@v3.4.1
         env:
           CIBW_SKIP: "pp*"
           CIBW_REPAIR_WHEEL_COMMAND: "LD_LIBRARY_PATH=$PWD/ggml/lib auditwheel repair -w {dest_dir} {wheel}"
           CIBW_ARCHS: "aarch64"
+          # Keep this consistent with the x86_64 Linux release wheels.
+          CIBW_MANYLINUX_AARCH64_IMAGE: "manylinux2014"
           # Keep native arm64 builds on a portable CPU baseline instead of
           # tuning wheels to the hosted runner.
           CIBW_ENVIRONMENT: CMAKE_ARGS="-DGGML_NATIVE=off -DGGML_METAL=OFF"
@@ -76,7 +86,7 @@ jobs:
           output-dir: wheelhouse
 
       - name: Upload wheels as artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: wheels_arm64
           path: ./wheelhouse/*.whl
@@ -88,12 +98,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           merge-multiple: true
           path: dist
 
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@v3
         with:
           files: dist/*
         env:

ggml_python-0.0.40/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.40]
+
+- fix(ci): rebuild wheel index after release asset workflows by @abetlen in #133
+- ci: update GitHub Actions workflow dependencies by @abetlen in #134
+- fix(ci): repair release wheel builds for cibuildwheel v3 by @abetlen in #135
+- feat(contrib): add ONNX backend by @dmille, @mrezanvari, and @abetlen in #23
+- feat: add missing ggml.h bindings by @abetlen in #118
+- feat: add CUDA backend bindings by @abetlen in #119
+- feat: add RPC backend bindings by @abetlen in #120
+- feat: add Vulkan backend registry binding by @abetlen in #121
+- feat: add BLAS backend bindings by @abetlen in #122
+- feat: add CANN backend bindings by @abetlen in #123
+- feat: add SYCL backend bindings by @abetlen in #124
+- feat: add OpenVINO backend bindings by @abetlen in #125
+- feat: add Hexagon backend bindings by @abetlen in #126
+- feat: add WebGPU backend bindings by @abetlen in #127
+- feat: add ZenDNN backend bindings by @abetlen in #128
+- feat: add zDNN backend bindings by @abetlen in #129
+- feat: add CPU conversion bindings by @abetlen in #130
+- feat: add arithmetic op bindings by @aisk in #114
+- fix: detect current optional backend symbols by @abetlen in #117
+- ci: increase Windows HIP SDK installer timeout by @abetlen in #112
+- ci: add tag triggers for release publishing workflows by @abetlen in #113
+
+## [0.0.39]
+
+- ci: add Vulkan wheel builds by @abetlen in #108
+- ci: add ROCm and Windows HIP wheel builds by @abetlen in #109
+- feat: add tensor layout helper bindings by @abetlen in #106
+- feat: add ggml_is_contiguous_{0,1,2} by @aisk in #95
+
+## [0.0.38]
+
+- ci: update pre-built wheels to py3-none and add CUDA 11.8-13.2 support by @abetlen in #104
+- feat: Update ggml to ggml-org/ggml@1e33fed3 and sync Python bindings by @abetlen in #100

{ggml_python-0.0.39 → ggml_python-0.0.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ggml_python
-Version: 0.0.39
+Version: 0.0.40
 Summary: Python bindings for ggml
 Author-Email: Andrei Betlen <abetlen@gmail.com>
 License: MIT
@@ -31,12 +31,21 @@ Provides-Extra: publish
 Requires-Dist: build; extra == "publish"
 Provides-Extra: convert
 Requires-Dist: accelerate==0.30.1; extra == "convert"
-Requires-Dist: numpy==1.26.4; extra == "convert"
-Requires-Dist: sentencepiece==0.2.0; extra == "convert"
+Requires-Dist: numpy==2.1.0; extra == "convert"
+Requires-Dist: sentencepiece==0.2.1; extra == "convert"
 Requires-Dist: torch==2.3.0; extra == "convert"
-Requires-Dist: torchaudio==2.3.0; extra == "convert"
+Requires-Dist: torchaudio==2.4.0; extra == "convert"
 Requires-Dist: torchvision==0.18.0; extra == "convert"
 Requires-Dist: transformers==4.41.2; extra == "convert"
+Provides-Extra: onnx
+Requires-Dist: onnx==1.14.0; extra == "onnx"
+Provides-Extra: onnx-tests
+Requires-Dist: numpy<2; extra == "onnx-tests"
+Requires-Dist: tabulate==0.9.0; extra == "onnx-tests"
+Requires-Dist: pytest-cov==4.1.0; extra == "onnx-tests"
+Requires-Dist: pytest-runner==6.0.0; extra == "onnx-tests"
+Requires-Dist: hypothesis[numpy]>=6.0.0; extra == "onnx-tests"
+Requires-Dist: onnxruntime==1.15.1; extra == "onnx-tests"
 Description-Content-Type: text/markdown
 
 # Python bindings for [`ggml`](https://github.com/ggml-org/ggml)
@@ -201,6 +210,21 @@ If you are having trouble installing `ggml-python` or activating specific featur
 pip install ggml-python --verbose --no-cache-dir --force-reinstall --upgrade
 ```
 
+## Native Crashes
+
+If you are debugging a `SIGSEGV`, `SIGABRT`, or `Aborted (core dumped)` failure, reproduce it with a debug build so native symbols are available.
+
+```bash
+git clone https://github.com/abetlen/ggml-python.git
+cd ggml-python
+make build.debug
+gdb --args python3 your_script.py
+```
+
+Inside `gdb`, use `run` to start the script, `bt` to inspect the native backtrace, and `py-bt` to inspect the Python backtrace when Python debug symbols are available.
+
+You can also use Python's built-in `breakpoint()` to stop before the native call that crashes.
+
 # License
 
 This project is licensed under the terms of the MIT license.

{ggml_python-0.0.39 → ggml_python-0.0.40}/README.md

@@ -160,6 +160,21 @@ If you are having trouble installing `ggml-python` or activating specific featur
 pip install ggml-python --verbose --no-cache-dir --force-reinstall --upgrade
 ```
 
+## Native Crashes
+
+If you are debugging a `SIGSEGV`, `SIGABRT`, or `Aborted (core dumped)` failure, reproduce it with a debug build so native symbols are available.
+
+```bash
+git clone https://github.com/abetlen/ggml-python.git
+cd ggml-python
+make build.debug
+gdb --args python3 your_script.py
+```
+
+Inside `gdb`, use `run` to start the script, `bt` to inspect the native backtrace, and `py-bt` to inspect the Python backtrace when Python debug symbols are available.
+
+You can also use Python's built-in `breakpoint()` to stop before the native call that crashes.
+
 # License
 
 This project is licensed under the terms of the MIT license.