[feat](pyvsag): publish macOS wheels

[jac0626]

Affected area

pyvsag

Motivation

pyvsag should be installable from PyPI on supported macOS systems without requiring users to build VSAG from source or install Homebrew-provided runtime libraries. This primarily benefits macOS development and demo workflows on both Apple Silicon and Intel Macs.

Proposed solution

Publish prebuilt macOS pyvsag wheels for CPython 3.10-3.14 on both arm64 and x86_64, targeting macOS 11.0 or newer.

The wheels should:

• build and test in GitHub Actions for both macOS architectures;
• use bundled dependencies for redistributable Python packaging;
• load the packaged libvsag.dylib via @loader_path;
• avoid Homebrew runtime dependencies such as libomp.dylib for ordinary pip install users;
• keep Linux wheel behavior unchanged.

Alternatives considered

• Keep macOS as a source-build-only path. This keeps CI simpler but does not satisfy direct pip install pyvsag usage on macOS.
• Require users to install Homebrew runtime libraries such as libomp before importing pyvsag. This is fragile for PyPI wheels because a clean user machine can fail at import time.
• Bundle libomp.dylib and keep OpenMP enabled for macOS wheels. This preserves more parallelism but adds runtime packaging complexity; macOS is expected to be used mostly for development and small demos rather than production server workloads.

API / ABI compatibility impact

additive only (no break)

References

• .github/workflows/build_release_wheel.yml:57 defines the macOS wheel matrix for CPython 3.10-3.14 on arm64 and x86_64.
• .github/workflows/build_release_wheel.yml:265 adds the macOS cibuildwheel build/test job.
• python/setup.py:38 applies macOS-specific wheel build settings.
• python/setup.py:44 disables OpenMP for macOS wheels to avoid an external libomp.dylib runtime dependency.
• python/setup.py:45 disables SOVERSION for macOS wheels so the wheel packages a single libvsag.dylib.
• docs/docs/en/src/guide/pyvsag.md:12 documents macOS wheel support.
• docs/docs/zh/src/guide/pyvsag.md:13 documents macOS wheel support in Chinese.

Additional context

Recent validation on the implementation branch confirms that CPython 3.10 macOS wheels build and test successfully on both Apple Silicon and Intel runners, and that the produced wheels contain a single packaged libvsag.dylib loaded via @loader_path with a macOS 11.0 deployment target.

Related issues

• Track macOS support #1890 Track macOS support: Track macOS support #1890
• Support pyvsag macOS wheel build and test #1892 Support pyvsag macOS wheel build and test: Support pyvsag macOS wheel build and test #1892

---

Drafted with AI assistant: Codex:GPT-5

[vsag-bot]

/module python