frost-gnn 0.3.1__tar.gz

frost_gnn-0.3.1/.env.example

@@ -0,0 +1,5 @@
+# Copy this file to .env.local and replace the example paths.
+# .env.local is loaded automatically.
+# Prepared data: https://huggingface.co/datasets/dttutty/frost_dataset
+FROST_DATA_ROOT=/path/to/frost_dataset
+TGB_DATA_ROOT=/path/to/tgb

frost_gnn-0.3.1/.github/scripts/build_pypi_release.py

@@ -0,0 +1,128 @@
+"""Build public distributions from a clean commit without a second README source."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import io
+import json
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import tomllib
+
+
+PUBLIC_INSTALL = """## 📦 Install
+
+On Linux x86-64 (glibc 2.31+) with Python 3.12:
+
+```bash
+python -m pip install frost_gnn
+```
+
+The Python import is `frost`; the command is `frost`. The CSV trainer runs on CPU
+unless you select a GPU. To use CPU-only PyTorch, install `torch==2.9.0` from
+`https://download.pytorch.org/whl/cpu` before installing FROST. CUDA execution
+requires a compatible NVIDIA driver.
+
+If upgrading from the old FROST 0.1.0 distribution, first run
+`python -m pip uninstall frost` to avoid overlapping package files.
+
+"""
+
+
+def public_readme(source: str) -> str:
+    """Reuse user documentation, stripping repository-only artwork and links."""
+    intro = source.index("A multi-GPU framework")
+    result = "# FROST\n\n" + source[intro:]
+    result, count = re.subn(
+        r"^## 📦 Install\n.*?(?=^## )",
+        PUBLIC_INSTALL,
+        result,
+        count=1,
+        flags=re.MULTILINE | re.DOTALL,
+    )
+    if count != 1:
+        raise ValueError("Expected exactly one installation section in README.md.")
+
+    def link(match):
+        label, target = match.groups()
+        if "://" in target or target.startswith(("#", "mailto:")):
+            return match.group(0)
+        return f"{label} (`{target.split('#')[0]}` in the source distribution)"
+
+    result = re.sub(r"\[([^\[\]]+)\]\(([^\s)]+)\)", link, result)
+    if "github.com/dttutty/frost_dev" in result:
+        raise ValueError(
+            "The public package description still contains private repository links."
+        )
+    return result
+
+
+def build(output: Path) -> None:
+    repo = Path(__file__).resolve().parents[2]
+    subprocess.run(["git", "diff", "--exit-code", "HEAD", "--"], cwd=repo, check=True)
+    commit = subprocess.check_output(
+        ["git", "rev-parse", "HEAD"], cwd=repo, text=True
+    ).strip()
+    output = output.resolve()
+    output.mkdir(parents=True, exist_ok=False)
+    raw, assets = output / "raw", output / "assets"
+    assets.mkdir()
+    archive = subprocess.check_output(["git", "archive", "HEAD"], cwd=repo)
+    with tempfile.TemporaryDirectory(prefix="frost-pypi-source-") as temp:
+        stage = Path(temp)
+        with tarfile.open(fileobj=io.BytesIO(archive)) as source:
+            source.extractall(stage, filter="data")
+        readme = stage / "README.md"
+        readme.write_text(public_readme(readme.read_text()))
+        metadata = tomllib.loads((stage / "pyproject.toml").read_text())["project"]
+        subprocess.run(["uv", "build", "--out-dir", str(raw)], cwd=stage, check=True)
+    wheels, sdists = list(raw.glob("*.whl")), list(raw.glob("*.tar.gz"))
+    if len(wheels) != 1 or len(sdists) != 1:
+        raise ValueError("Expected one wheel and one source distribution.")
+    subprocess.run(
+        [
+            "uvx",
+            "--with",
+            "patchelf",
+            "auditwheel",
+            "repair",
+            "--plat",
+            "manylinux_2_31_x86_64",
+            "--wheel-dir",
+            str(assets),
+            str(wheels[0]),
+        ],
+        check=True,
+    )
+    shutil.copy2(sdists[0], assets / sdists[0].name)
+    subprocess.run(
+        ["uvx", "twine", "check", *map(str, sorted(assets.iterdir()))], check=True
+    )
+    info = {
+        "distribution": metadata["name"],
+        "version": metadata["version"],
+        "source_commit": commit,
+        "platform": "manylinux_2_31_x86_64",
+        "python": "3.12",
+        "readme": "Generated from README.md by build_pypi_release.py",
+    }
+    (assets / "BUILD_INFO.json").write_text(json.dumps(info, indent=2) + "\n")
+    manifest = "".join(
+        f"{hashlib.sha256(p.read_bytes()).hexdigest()}  {p.name}\n"
+        for p in sorted(assets.iterdir())
+    )
+    (assets / "SHA256SUMS").write_text(manifest)
+    print(f"Release artifacts: {assets}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--output", type=Path, required=True, help="New build directory."
+    )
+    build(parser.parse_args().output)

frost_gnn-0.3.1/.github/scripts/update_coverage_badge.py

@@ -0,0 +1,40 @@
+"""Update the README badge from a real coverage.py JSON report."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("report", type=Path)
+    args = parser.parse_args()
+    totals = json.loads(args.report.read_text())["totals"]
+    total = int(totals["num_statements"])
+    covered = int(totals["covered_lines"])
+    if not 0 <= covered <= total or total == 0:
+        raise ValueError("Coverage report must contain a nonempty Python source measurement")
+    percent = 100 * covered / total
+    color = "brightgreen" if percent >= 80 else "yellowgreen" if percent >= 60 else "orange"
+    repository = os.environ.get("GITHUB_REPOSITORY", "dttutty/frost_dev")
+    badge = (
+        f"[![CPU coverage](https://img.shields.io/badge/CPU%20coverage-"
+        f"{percent:.1f}%25-{color})]"
+        f"(https://github.com/{repository}/actions/workflows/coverage.yml)"
+    )
+    readme = Path(__file__).resolve().parents[2] / "README.md"
+    updated, count = re.subn(
+        r"^\[!\[CPU coverage\].*$", badge, readme.read_text(), flags=re.MULTILINE
+    )
+    if count != 1:
+        raise ValueError(f"Expected one CPU coverage badge in README, found {count}")
+    readme.write_text(updated)
+    print(f"CPU Python line coverage: {covered}/{total} = {percent:.1f}%")
+
+
+if __name__ == "__main__":
+    main()

frost_gnn-0.3.1/.github/scripts/verify_pypi_release.py

@@ -0,0 +1,95 @@
+"""Verify private release assets before copying public distributions to dist/."""
+
+from __future__ import annotations
+
+import argparse
+from email.parser import BytesParser
+import hashlib
+import json
+from pathlib import Path
+import re
+import shutil
+import tarfile
+import zipfile
+
+
+def verify(source: Path, output: Path, tag: str, commit: str) -> None:
+    if not re.fullmatch(r"v\d+\.\d+\.\d+(?:(?:a|b|rc)\d+)?", tag):
+        raise ValueError("Expected a version tag such as v0.3.1.")
+    version = tag[1:]
+    hashes = {}
+    for line in (source / "SHA256SUMS").read_text().splitlines():
+        digest, name = line.split("  ", 1)
+        if (
+            not re.fullmatch(r"[a-f0-9]{64}", digest)
+            or Path(name).name != name
+            or name in hashes
+        ):
+            raise ValueError("Invalid checksum manifest entry.")
+        hashes[name] = digest
+    files = {p.name for p in source.iterdir() if p.is_file()} - {"SHA256SUMS"}
+    if files != hashes.keys():
+        raise ValueError("Checksum manifest must cover every release asset.")
+    for name, digest in hashes.items():
+        if hashlib.sha256((source / name).read_bytes()).hexdigest() != digest:
+            raise ValueError(f"Checksum mismatch: {name}")
+    info = json.loads((source / "BUILD_INFO.json").read_text())
+    if info["version"] != version or info["source_commit"] != commit:
+        raise ValueError("Release version or source commit does not match the tag.")
+    distributions = sorted(
+        p for p in source.iterdir() if p.suffix == ".whl" or p.name.endswith(".tar.gz")
+    )
+    if (
+        not any(p.suffix == ".whl" for p in distributions)
+        or sum(p.name.endswith(".tar.gz") for p in distributions) != 1
+    ):
+        raise ValueError("Expected at least one wheel and one source distribution.")
+    for path in distributions:
+        if path.suffix == ".whl":
+            with zipfile.ZipFile(path) as wheel:
+                names = [
+                    n for n in wheel.namelist() if n.endswith(".dist-info/METADATA")
+                ]
+                if len(names) != 1:
+                    raise ValueError("Expected one wheel metadata record.")
+                metadata = wheel.read(names[0])
+        else:
+            with tarfile.open(path) as sdist:
+                names = [
+                    m
+                    for m in sdist.getmembers()
+                    if m.name.count("/") == 1 and m.name.endswith("/PKG-INFO")
+                ]
+                if len(names) != 1:
+                    raise ValueError("Expected one source metadata record.")
+                stream = sdist.extractfile(names[0])
+                if stream is None:
+                    raise ValueError("Missing source metadata.")
+                metadata = stream.read()
+        record = BytesParser().parsebytes(metadata)
+        name = re.sub(r"[-_.]+", "-", record["Name"]).lower()
+        if name != "frost-gnn" or record["Version"] != version:
+            raise ValueError(f"Wrong distribution name/version: {path.name}")
+        if (
+            b"github.com/dttutty/frost_dev" in metadata
+            or b"not available yet" in metadata
+        ):
+            raise ValueError(
+                "Distribution description is not ready for public installation."
+            )
+    output.mkdir(parents=True, exist_ok=False)
+    for path in distributions:
+        shutil.copy2(path, output / path.name)
+    print(
+        f"Verified {len(distributions)} frost-gnn {version} distributions from {commit}."
+    )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--source", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--tag", required=True)
+    parser.add_argument("--commit", required=True)
+    args = parser.parse_args()
+    verify(args.source, args.output, args.tag, args.commit)

frost_gnn-0.3.1/.github/workflows/coverage.yml

@@ -0,0 +1,88 @@
+name: CPU coverage
+
+on:
+  push:
+    branches: [main]
+    paths-ignore: [README.md]
+  pull_request:
+    paths-ignore: [README.md]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cpu-coverage-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+    env:
+      CUDA_VISIBLE_DEVICES: ""
+      OMP_NUM_THREADS: "2"
+      MKL_NUM_THREADS: "2"
+      CMAKE_BUILD_PARALLEL_LEVEL: "2"
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install CPU test environment
+        run: |
+          uv venv --python 3.12
+          uv pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/cpu
+          uv pip install --no-sources -e . pytest pytest-cov
+      - name: Measure Python line coverage
+        run: >-
+          uv run --no-sync pytest tests/ -q
+          --cov=src/frost --cov-report=term:skip-covered
+          --cov-report=json:coverage.json --cov-report=html:htmlcov
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: cpu-coverage
+          path: |
+            coverage.json
+            htmlcov/
+          retention-days: 14
+          if-no-files-found: warn
+
+  badge:
+    needs: tests
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-22.04
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ github.sha }}
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: cpu-coverage
+          path: ${{ runner.temp }}/cpu-coverage
+      - name: Update measured badge on the tested revision
+        env:
+          COVERAGE_REPORT: ${{ runner.temp }}/cpu-coverage/coverage.json
+        run: |
+          uv run --no-project --python 3.12 python .github/scripts/update_coverage_badge.py "$COVERAGE_REPORT"
+          if git diff --quiet -- README.md; then
+            exit 0
+          fi
+          git fetch origin main
+          if [ "$(git rev-parse origin/main)" != "$GITHUB_SHA" ]; then
+            echo "main advanced; a newer run will update the badge."
+            exit 0
+          fi
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add README.md
+          git commit -m 'docs: update CPU coverage badge'
+          git push origin HEAD:main

frost_gnn-0.3.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,71 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Verified GitHub Release tag, e.g. v0.3.1'
+        required: true
+        type: string
+      dry_run:
+        description: 'Validate artifacts without publishing'
+        required: true
+        default: true
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-publication
+  cancel-in-progress: false
+
+jobs:
+  prepare:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
+        with:
+          python-version: '3.12'
+      - name: Download and verify release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.release_tag }}
+        run: |
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$ ]]
+          gh release download "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --dir release-assets
+          release_commit=$(git rev-parse --verify "${RELEASE_TAG}^{commit}")
+          uv run --no-project --python 3.12 python .github/scripts/verify_pypi_release.py \
+            --source release-assets --output dist --tag "$RELEASE_TAG" --commit "$release_commit"
+          uvx twine check dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: pypi-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    needs: prepare
+    if: github.ref == 'refs/heads/main' && !inputs.dry_run
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/frost-gnn/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: pypi-distributions
+          path: dist/
+      - name: Publish verified distributions
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          packages-dir: dist/

frost_gnn-0.3.1/.gitignore

@@ -0,0 +1,109 @@
+# Data & model artifacts
+/models/
+checkpoints/
+data/
+!src/frost/data/
+!src/frost/data/*.py
+datasets/
+*.pt
+*.pth
+*.pkl
+*.h5
+*.ckpt
+*.gz
+*.zip
+
+# Build
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+*.so
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.venv/
+env/
+venv/
+ENV/
+.pytest_cache/
+.mypy_cache/
+
+# Logs & outputs
+outputs/
+logs/
+artifacts/
+/results/
+*.log
+
+# Experiment
+experiment_logs*
+result.json
+_tgmem_out/
+wandb/
+.wandb/
+tensorboard/
+runs/
+slurm/
+
+# IDE & OS
+.idea/
+.claude/
+*.swp
+*.swo
+*~
+.DS_Store
+.ipynb_checkpoints/
+*.ipynb
+
+# Paper repositories are maintained outside the code repository.
+/overleaf/
+/revision/
+
+# Misc
+.env.local
+.trash/
+.ruff_cache/
+hydralance/
+temp/
+traces/
+
+DATA/DGB*
+DATA/.temp
+DATA/TGL*
+TGL_DATA/
+/DATA
+tmp/
+*.tar
+*.tar.gz
+
+# Generated experiment artifacts
+seed_sweeps/**
+seed_sweeps_old/**
+
+download_data.sh
+*.txt
+*.tsv
+
+# Local reproduction tools and compatibility navigation (not part of the library).
+/benchmarks
+/docs/artifact_organization.md
+/docs/camera_ready_sources.md
+/.vscode/launch.json
+/.vscode/tasks.json

frost_gnn-0.3.1/.python-version

@@ -0,0 +1 @@
+3.12

frost_gnn-0.3.1/.vscode/settings.json

@@ -0,0 +1,119 @@
+{
+  "git.detectSubmodules": true,
+  "git.detectSubmodulesLimit": 30,
+  "git.autoRepositoryDetection": true,
+  "scm.alwaysShowRepositories": true,
+  "scm.repositories.selectionMode": "multiple",
+
+  "ruff.nativeServer": "auto",
+  "python.languageServer": "Pylance",
+  "python.analysis.typeCheckingMode": "basic",
+  "python.analysis.diagnosticMode": "openFilesOnly",
+  "python.analysis.indexing": false,
+  "python.analysis.exclude": [
+    "**/.*",
+    "**/.git",
+    "**/__pycache__",
+    "**/.ruff_cache",
+    "**/node_modules",
+    "**/logs",
+    "**/checkpoints",
+    "**/wandb",
+    "**/data",
+    "**/outputs",
+    "**/build",
+    "**/dist",
+    "**/.venv",
+    "**/third_party"
+  ],
+  "python.analysis.extraPaths": [
+    "./src"
+  ],
+  "python.autoComplete.extraPaths": [
+    "./src"
+  ],
+
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  },
+
+  "files.watcherExclude": {
+    "**/.git/**": true,
+    "**/__pycache__/**": true,
+    "**/.ruff_cache/**": true,
+    "**/node_modules/**": true,
+    "**/logs/**": true,
+    "**/checkpoints/**": true,
+    "**/wandb/**": true,
+    "**/data/**": true,
+    "**/outputs/**": true,
+    "**/build/**": true,
+    "**/dist/**": true,
+    "**/.venv/**": true,
+    "**/third_party/**": true
+  },
+  "files.exclude": {
+    "**/.git": true,
+    "**/.svn": true,
+    "**/.hg": true,
+    "**/.DS_Store": true,
+    "**/Thumbs.db": true,
+    "**/.venv": true,
+    "**/build": true,
+    "**/dist": true,
+    "hydralance": true
+  },
+
+  "cmake.configureSettings": {
+    "Python_EXECUTABLE": "${workspaceFolder}/.venv/bin/python",
+    "nanobind_DIR": "${workspaceFolder}/.venv/lib/python3.12/site-packages/nanobind/cmake"
+  },
+
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python-envs.defaultEnvManager": "ms-python.python:venv",
+  "python-envs.defaultPackageManager": "ms-python.python:pip",
+
+  "latex-workshop.latex.autoBuild.run": "onSave",
+  "latex-workshop.latex.recipe.default": "first",
+  "latex-workshop.latex.recipes": [
+    {
+      "name": "latexmk",
+      "tools": ["latexmk"]
+    }
+  ],
+  "latex-workshop.latex.tools": [
+    {
+      "name": "latexmk",
+      "command": "latexmk",
+      "args": [
+        "-pdf",
+        "-synctex=1",
+        "-interaction=nonstopmode",
+        "-file-line-error",
+        "-outdir=%OUTDIR%",
+        "%DOC%"
+      ],
+      "env": {
+        "PATH": "${env:PATH}"
+      }
+    }
+  ],
+  "latex-workshop.latex.clean.command": "latexmk",
+
+  "hydralance.excludePatterns": [
+    ".venv/**",
+    "outputs/**",
+    "third_party/**"
+  ],
+  "hydralance.hideHelperFolder": true,
+
+  "workbench.editorAssociations": {
+    "README.md": "vscode.markdown.preview.editor",
+    "**/README.md": "vscode.markdown.preview.editor"
+  }
+}