v3: migrate main to immutable Tree, unified sweeps, and BFFG refit

.github/workflows/docs.yaml

@@ -0,0 +1,68 @@
+name: Docs
+
+on:
+  push:
+    branches: [main, v3]
+  pull_request:
+    branches: [main, v3]
+  workflow_dispatch:
+
+# Allow one concurrent deployment; cancel in-progress runs on the same ref.
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Sphinx build (strict)
+    runs-on: ubuntu-latest
+    env:
+      # PR merge refs see upstream's legacy non-v tags but not the fork's v3 tag.
+      SETUPTOOLS_SCM_PRETEND_VERSION_FOR_HYPERIAX: "3.0.0"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # setuptools-scm needs the full history + tags to derive __version__
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Sync project (core runtime + dev group)
+        run: uv sync --group dev
+
+      - name: Build HTML (warnings as errors)
+        run: uv run make -C docs html SPHINXOPTS=-W
+
+      - name: Upload Pages artifact
+        # Only the deployable ref needs to upload; PRs just verify the build.
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/v3'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/v3'
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    permissions:
+      pages: write       # to deploy to Pages
+      id-token: write    # to verify the deployment originates from this workflow
+
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pypi_push.yaml

@@ -1,38 +1,35 @@
-name: Publish Package
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-
-jobs:
-  pypi-publish:
-    name: Upload release to PyPI
-    runs-on: ubuntu-latest
-    environment:
-      name: pypi
-      url: https://pypi.org/p/hyperiax
-    permissions:
-      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
-    steps:
-    # retrieve your distributions here
-    - name: Setup python
-      uses: actions/setup-python@v4
-      with:
-        python-version: "3.11"
-    - name: Setup setuptools_scm
-      run: pip install setuptools_scm
-    - name: Checkout the repository
-      uses: actions/checkout@v2
-    - name: Build package
-      run: python setup.py sdist
-     # working-directory: ./app
-
-
-    - name: Publish package distributions to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        password: ${{ secrets.PYPI_API_TOKEN }}
+name: Publish Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hyperiax
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+      contents: read
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0   # setuptools-scm needs the full history for the version tag
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Build sdist + wheel
+      run: uv build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/pytest.yaml

@@ -1,30 +1,27 @@
-name: Pytest on Pull Request
+name: Test
 
 on:
   push:
-    branches:
-      - main
+    branches: [main, v3]
   pull_request:
-    branches:
-      - main
+    branches: [main, v3]
 
 jobs:
   test:
-    name: Run Pytest
+    name: pytest (uv, Python 3.11)
     runs-on: ubuntu-latest
-    
+
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
-      
-    - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
       with:
-        python-version: 3.11
-
-    - name: Install dependencies
-      run: |
-        pip install .[dev]
-
-    - name: Run Pytest
-      run: make test
+        enable-cache: true
+
+    - name: Sync project (core runtime + dev group)
+      run: uv sync --group dev
+
+    - name: Run tests
+      run: uv run pytest

.gitignore

@@ -77,6 +77,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
+docs/source/api/generated/
 
 # PyBuilder
 .pybuilder/
@@ -168,14 +170,22 @@ cython_debug/
 #.idea/
 
 legacy/
-# docs/
 data/
 todo
 changelog
-# generated on build server
+# generated by setuptools-scm on build
 *_version.py
-examples/example_data
-*test.ipynb
 *.cpp
 .vscode/
 .Rproj.user
+
+# OS
+.DS_Store
+
+# Note: uv.lock IS committed (do not ignore) — needed for reproducible installs.
+
+.claude/
+.ruff_cache/
+
+# Throwaway profiling scratchpad outputs.
+/profiling/traces/

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# Hyperiax pre-commit hooks.
+#
+# Install once per clone:
+#   uv run pre-commit install
+# Run on all files:
+#   uv run pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.13
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^(docs/build/|docs/source/notebooks/)
+      - id: end-of-file-fixer
+        exclude: ^(docs/build/|docs/source/notebooks/|hyperiax/_version\.py$)
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]

.python-version

@@ -0,0 +1 @@
+3.11