Metadata-Version: 2.4
Name: pyg-hyper
Version: 0.1.2
Summary: Unified interface for PyTorch Geometric Hypergraph Learning
Project-URL: Homepage, https://github.com/nishide-dev/pyg-hyper
Project-URL: Repository, https://github.com/nishide-dev/pyg-hyper
Project-URL: Issues, https://github.com/nishide-dev/pyg-hyper/issues
Author-email: Ryusei Nishide <nishide.dev@gmail.com>
License: MIT
Keywords: graph-neural-networks,hypergraph,machine-learning,pytorch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Provides-Extra: all
Requires-Dist: pyg-hyper-bench<0.2.0,>=0.1.1; extra == 'all'
Requires-Dist: pyg-hyper-data<0.2.0,>=0.1.1; extra == 'all'
Requires-Dist: pyg-hyper-nn<0.2.0,>=0.1.1; extra == 'all'
Requires-Dist: pyg-hyper-ssl<0.2.0,>=0.1.1; extra == 'all'
Provides-Extra: bench
Requires-Dist: pyg-hyper-bench<0.2.0,>=0.1.1; extra == 'bench'
Provides-Extra: data
Requires-Dist: pyg-hyper-data<0.2.0,>=0.1.1; extra == 'data'
Provides-Extra: nn
Requires-Dist: pyg-hyper-nn<0.2.0,>=0.1.1; extra == 'nn'
Provides-Extra: ssl
Requires-Dist: pyg-hyper-ssl<0.2.0,>=0.1.1; extra == 'ssl'
Description-Content-Type: text/markdown

# 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.

## Prerequisites

This package requires PyTorch Geometric to be installed:

```bash
pip install torch torch-geometric
```

## Installation

### Install all components

```bash
pip install pyg-hyper[all]
```

Or with uv:

```bash
uv add pyg-hyper[all]
```

### Install Specific Components

```bash
# 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

### Import Style

Import directly from each sub-package:

```python
from pyg_hyper.data.datasets import CoraCocitation
from pyg_hyper.bench import NodeClassificationProtocol, SingleRunEvaluator
from pyg_hyper.ssl import TriCL, TriCLEncoder
```

### Dataset Loading

```python
from pyg_hyper.data.datasets import CoraCocitation

dataset = CoraCocitation()
data = dataset[0]
print(data)  # HyperData with x, hyperedge_index, y
```

### SSL Training & Evaluation

```python
from pyg_hyper.data.datasets import CoraCocitation
from pyg_hyper.ssl import TriCL, TriCLEncoder
from pyg_hyper.bench import SSLLinearEvaluationProtocol

dataset = CoraCocitation()
data = dataset[0]

# Build encoder and SSL model
encoder = TriCLEncoder(
    in_dim=data.num_node_features,
    edge_dim=64,
    node_dim=64,
    num_layers=2,
)
model = TriCL(encoder=encoder, proj_dim=64)

# Get embeddings for downstream evaluation
embeddings = model.get_embeddings(data)  # [num_nodes, node_dim]

# Linear evaluation
protocol = SSLLinearEvaluationProtocol(seed=42)
split = protocol.split_data(data)
metrics = protocol.evaluate(
    embeddings=embeddings,
    labels=data.y,
    train_mask=split["train_mask"],
    val_mask=split["val_mask"],
    test_mask=split["test_mask"],
)
print(f"Test Accuracy: {metrics['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](https://github.com/nishide-dev/pyg-hyper) | Hypergraph datasets (11 datasets) | 0.1.1 |
| [pyg-hyper-nn](https://github.com/nishide-dev/pyg-hyper) | Neural network layers | 0.1.1 |
| [pyg-hyper-ssl](https://github.com/nishide-dev/pyg-hyper) | Self-supervised learning | 0.1.1 |
| [pyg-hyper-bench](https://github.com/nishide-dev/pyg-hyper) | Benchmarking framework | 0.1.1 |

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/nishide-dev/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

```bash
# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run ty check src/
```

### Testing

```bash
# 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:
```bash
uv run pre-commit install
```

Run manually:
```bash
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

```bash
# 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:

```bibtex
@software{pyg_hyper,
  title = {pyg-hyper: Unified PyTorch Geometric Hypergraph Learning},
  author = {Ryusei Nishide},
  year = {2026},
  url = {https://github.com/nishide-dev/pyg-hyper}
}
```
