Add HIF/Python interoperability and reproducible ecosystem benchmarks

.github/workflows/python.yml

@@ -0,0 +1,285 @@
+name: python wheels and release
+
+on:
+  push:
+    branches: [main]
+    tags: ["python-v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  metadata:
+    name: Package and release version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Check package versions and release tag
+        run: |
+          python - <<'PYTHON'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          package = tomllib.loads(Path('crates/hyper-viz-python/pyproject.toml').read_text())
+          workspace = tomllib.loads(Path('Cargo.toml').read_text())
+          desktop = tomllib.loads(Path('pyproject.toml').read_text())
+          version = package['project']['version']
+          assert desktop['project']['version'] == version, 'Desktop and core versions differ'
+          assert package['project']['optional-dependencies']['viewer'] == [f'hypergraph-viz-viewer=={version}']
+          assert version == workspace['workspace']['package']['version'], 'Python and Rust versions differ'
+          if os.environ['GITHUB_REF_TYPE'] == 'tag':
+              assert os.environ['GITHUB_REF_NAME'] == f'python-v{version}', 'Tag must match package version'
+          print(f"{package['project']['name']} {version}: metadata matches")
+          PYTHON
+
+  wheels:
+    name: ${{ matrix.target }} / CPython abi3
+    needs: metadata
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-14
+            target: aarch64-apple-darwin
+          - os: macos-15-intel
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    env:
+      CARGO_TERM_COLOR: always
+      MACOSX_DEPLOYMENT_TARGET: '11.0'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - uses: dtolnay/rust-toolchain@1.89.0
+        with:
+          targets: ${{ matrix.target }}
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: Install test tools
+        run: python -m pip install -r crates/hyper-viz-python/requirements-test.txt
+      - name: Generate stubs and check drift
+        run: |
+          cargo run --locked -p hyper-viz-python --bin stub_gen
+          git diff --exit-code -- crates/hyper-viz-python/python/hyper_viz/_core.pyi
+      - name: Rust checks (no Bevy dependency)
+        run: |
+          cargo fmt --all -- --check
+          cargo clippy --locked -p hyper-viz -p hyper-viz-python --all-targets -- -D warnings
+          cargo test --locked --offline -p hyper-viz
+      - name: Build platform wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          maturin-version: '1.9.6'
+          target: ${{ matrix.target }}
+          manylinux: auto
+          args: --release --locked --manifest-path crates/hyper-viz-python/Cargo.toml --out dist
+      - name: Install built wheel
+        shell: bash
+        run: python -m pip install --no-deps dist/*.whl
+      - name: Test installed package
+        run: |
+          python -m pytest crates/hyper-viz-python/tests -q
+          python -m mypy --strict crates/hyper-viz-python/python/hyper_viz
+          python crates/hyper-viz-python/examples/xgi_interop.py
+      - name: Check wheel contents
+        run: python crates/hyper-viz-python/tests/check_wheel.py dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: hyper-viz-${{ matrix.target }}
+          path: dist/*.whl
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Clean-install ABI compatibility smoke test
+        shell: bash
+        run: |
+          python -m pip install --no-deps dist/*.whl
+          python -c 'from hyper_viz import HifDocument; assert "s:a" in HifDocument.from_json("{\"incidences\":[{\"node\":\"a\",\"edge\":\"e\"}]}").to_hypergraph_json()'
+
+  sdist:
+    name: Source distribution
+    needs: metadata
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: dtolnay/rust-toolchain@1.89.0
+      - uses: Swatinem/rust-cache@v2
+      - name: Build and unpack source distribution
+        shell: bash
+        run: |
+          python -m pip install maturin==1.9.6
+          python scripts/releases/build_python_sdist.py --out dist
+          mkdir packaged-source
+          tar -xzf dist/*.tar.gz -C packaged-source --strip-components=1
+      - name: Build wheel from packaged source
+        working-directory: packaged-source
+        run: maturin build --release --locked --out ../sdist-wheel
+      - name: Verify wheel built from packaged source
+        shell: bash
+        run: |
+          python crates/hyper-viz-python/tests/check_wheel.py sdist-wheel
+          python -m pip install --no-deps sdist-wheel/*.whl
+          python -c 'from hyper_viz import HifDocument; HifDocument.from_json("{\"incidences\":[]}").to_hypergraph_json()'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: hyper-viz-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+
+  desktop:
+    name: ${{ matrix.target }} / desktop viewer
+    needs: metadata
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-14
+            target: aarch64-apple-darwin
+          - os: macos-15-intel
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    env:
+      CARGO_TERM_COLOR: always
+      MACOSX_DEPLOYMENT_TARGET: '11.0'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - uses: dtolnay/rust-toolchain@1.89.0
+        with:
+          targets: ${{ matrix.target }}
+      - uses: Swatinem/rust-cache@v2
+      - name: Check desktop native dependencies
+        run: python scripts/releases/check_desktop_dependencies.py
+      - name: Install Windows binary inspection tool
+        if: runner.os == 'Windows'
+        run: python -m pip install pefile==2024.8.26
+      - name: Build desktop wheel
+        uses: PyO3/maturin-action@v1
+        env:
+          RUSTFLAGS: ${{ runner.os == 'Windows' && '-C target-feature=+crt-static' || '' }}
+        with:
+          maturin-version: '1.9.6'
+          rust-toolchain: '1.89.0'
+          target: ${{ matrix.target }}
+          manylinux: '2_28'
+          before-script-linux: yum install -y wayland-devel libxkbcommon-devel
+          args: --release --locked --auditwheel check --out desktop-dist
+      - name: Check desktop wheel contents
+        run: python scripts/releases/check_desktop_wheel.py desktop-dist
+      - name: Install and verify standalone desktop binary
+        shell: bash
+        run: |
+          python -m pip install --no-index --only-binary=:all: desktop-dist/*.whl
+          python scripts/releases/smoke_desktop.py --viewer-only
+      - uses: actions/upload-artifact@v4
+        with:
+          name: hyper-viz-desktop-${{ matrix.target }}
+          path: desktop-dist/*.whl
+          if-no-files-found: error
+
+
+  desktop-integration:
+    name: ${{ matrix.target }} / installed viewer extra
+    needs: [wheels, desktop]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: macos-14
+            target: aarch64-apple-darwin
+          - os: macos-15-intel
+            target: x86_64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - uses: actions/download-artifact@v4
+        with:
+          name: hyper-viz-desktop-${{ matrix.target }}
+          path: desktop-dist
+      - uses: actions/download-artifact@v4
+        with:
+          name: hyper-viz-${{ matrix.target }}
+          path: core-dist
+      - name: Install core and viewer together without source builds
+        shell: bash
+        run: |
+          python -m pip install --no-index --only-binary=:all: --find-links core-dist --find-links desktop-dist 'hypergraph-viz[viewer]'
+      - name: Verify executable discovery and CLI startup
+        run: python scripts/releases/smoke_desktop.py
+      - name: Install Linux graphics test runtime
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y xvfb libvulkan1 mesa-vulkan-drivers libegl1 libxkbcommon-x11-0 libwayland-client0 libx11-6 libxrandr2 libxi6 libxcursor1
+      - name: Verify native window on software Vulkan
+        if: runner.os == 'Linux'
+        env:
+          WGPU_BACKEND: vulkan
+          WINIT_UNIX_BACKEND: x11
+          HYPER_VIZ_SESSION: 'off'
+        run: xvfb-run -a python scripts/releases/smoke_desktop.py --render
+      - uses: actions/upload-artifact@v4
+        if: runner.os == 'Linux' && always()
+        with:
+          name: desktop-render-smoke
+          path: target/desktop-smoke/render.png
+          if-no-files-found: ignore
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/python-v')
+    needs: [wheels, sdist, desktop-integration]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hypergraph-viz/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: hyper-viz-*
+          merge-multiple: true
+          path: dist
+      - name: Separate companion and core distributions
+        run: |
+          mkdir desktop-release core-release
+          mv dist/hypergraph_viz_viewer-*.whl desktop-release/
+          mv dist/* core-release/
+      - name: Publish desktop companion with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: desktop-release/
+      - name: Publish core after companion is available
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: core-release/

.gitignore

@@ -1,3 +1,13 @@
 /target
 .env
 
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+scripts/benchmarks/browser/node_modules/
+
+# Editable maturin builds place the extension in the Python source package.
+/crates/hyper-viz-python/python/hyper_viz/*.so
+/crates/hyper-viz-python/python/hyper_viz/*.pyd