pyg-hyper 0.1.0

Unified interface for PyTorch Geometric Hypergraph Learning

pyg-hyper: Unified PyTorch Geometric Hypergraph Learning

Unified interface for all pyg-hyper components, providing convenient access to hypergraph datasets, neural network layers, self-supervised learning methods, and benchmarking protocols.

Installation

Install All Components

pip install pyg-hyper[all]

Install Specific Components

# Data only
pip install pyg-hyper[data]

# Neural networks only
pip install pyg-hyper[nn]

# Self-supervised learning
pip install pyg-hyper[ssl]

# Benchmarking
pip install pyg-hyper[bench]

# Combine multiple
pip install pyg-hyper[data,nn]

Quick Start

Unified Imports

from pyg_hyper import data, nn, ssl, bench

# Load dataset
dataset = data.CoraCocitation()
hyper_data = dataset[0]

# Create model
model = nn.HyperGraphSage(
    in_channels=hyper_data.num_node_features,
    hidden_channels=64,
    out_channels=dataset.num_classes,
    num_layers=2,
)

# Evaluate with benchmark
protocol = bench.NodeClassificationProtocol(seed=42)
evaluator = bench.SingleRunEvaluator(protocol)
result = evaluator.evaluate(model, dataset)
print(f"Test Accuracy: {result['test_accuracy']:.4f}")

SSL Workflow

from pyg_hyper import data, nn, ssl, bench

# Load dataset
dataset = data.CoraCocitation()
hyper_data = dataset[0]

# Create SSL encoder
encoder = nn.HyperGraphSage(
    in_channels=hyper_data.num_node_features,
    hidden_channels=64,
    out_channels=64,
    num_layers=2,
)

# Pre-train with SSL (placeholder - implement in pyg-hyper-ssl)
# ssl_trainer = ssl.MaskedNodePrediction(encoder)
# ssl_trainer.fit(dataset)

# Evaluate frozen embeddings
import torch
with torch.no_grad():
    embeddings = encoder(hyper_data.x, hyper_data.incidence_matrix)

protocol = bench.SSLLinearEvaluationProtocol(
    task="node_classification",
    classifier="logistic_regression",
    seed=42,
)
result = protocol.evaluate(embeddings, hyper_data)
print(f"Linear Probe Accuracy: {result['test_accuracy']:.4f}")

Architecture

This is a pure meta-package that provides:

• ✅ Unified import interface via lazy loading
• ✅ Zero import overhead (loads only what you use)
• ✅ Independent versioning of sub-packages
• ✅ Maximum flexibility (install only what you need)

Sub-Packages

Package	Description	Version
pyg-hyper-data	Hypergraph datasets (10 datasets)	0.1.0
pyg-hyper-nn	Neural network layers	0.1.0
pyg-hyper-ssl	Self-supervised learning	0.1.0
pyg-hyper-bench	Benchmarking framework	0.1.0

Development

Setup

# Clone repository
git clone https://github.com/your-username/pyg-hyper.git
cd pyg-hyper

# Install with dev dependencies
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

Code Quality

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run ty check src/

Testing

# Run all tests
uv run pytest tests/ -v

# Run only import tests
uv run pytest tests/test_imports.py -v

# Run only integration tests
uv run pytest tests/ -v -m integration

# With coverage
uv run pytest tests/ --cov=pyg_hyper --cov-report=html

Pre-commit Hooks

Automatically run code quality checks before commits:

• ruff-lint: Linting with auto-fix
• ruff-format: Code formatting
• ty-check: Type checking

Install hooks:

uv run pre-commit install

Run manually:

uv run pre-commit run --all-files

CI/CD

GitHub Actions

• CI Pipeline: Code quality, import tests, integration tests
• Publish Pipeline: Automatic publishing to TestPyPI (main branch) and PyPI (tags)

Publishing

# TestPyPI (automatic on push to main)
uv publish --index testpypi

# PyPI (automatic on tag v*)
git tag v0.1.0
git push origin v0.1.0

License

MIT License - See LICENSE file for details.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run pre-commit hooks
4. Submit a pull request

Citation

If you use pyg-hyper in your research, please cite:

@software{pyg_hyper,
  title = {pyg-hyper: Unified PyTorch Geometric Hypergraph Learning},
  author = {Nishide, Takumi},
  year = {2026},
  url = {https://github.com/your-username/pyg-hyper}
}