Metadata-Version: 2.4
Name: pyg-hyper
Version: 0.1.0
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: Takumi Nishide <nishide.takumi@gmail.com>
License: MIT
License-File: LICENSE
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.0; extra == 'all'
Requires-Dist: pyg-hyper-data<0.2.0,>=0.1.0; extra == 'all'
Requires-Dist: pyg-hyper-nn<0.2.0,>=0.1.0; extra == 'all'
Requires-Dist: pyg-hyper-ssl<0.2.0,>=0.1.0; extra == 'all'
Provides-Extra: bench
Requires-Dist: pyg-hyper-bench<0.2.0,>=0.1.0; extra == 'bench'
Provides-Extra: data
Requires-Dist: pyg-hyper-data<0.2.0,>=0.1.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: nn
Requires-Dist: pyg-hyper-nn<0.2.0,>=0.1.0; extra == 'nn'
Provides-Extra: ssl
Requires-Dist: pyg-hyper-ssl<0.2.0,>=0.1.0; 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.

## Installation

### Install All Components

```bash
pip install 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

### Unified Imports

```python
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

```python
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](https://github.com/your-username/pyg-hyper-data) | Hypergraph datasets (10 datasets) | 0.1.0 |
| [pyg-hyper-nn](https://github.com/your-username/pyg-hyper-nn) | Neural network layers | 0.1.0 |
| [pyg-hyper-ssl](https://github.com/your-username/pyg-hyper-ssl) | Self-supervised learning | 0.1.0 |
| [pyg-hyper-bench](https://github.com/your-username/pyg-hyper-bench) | Benchmarking framework | 0.1.0 |

## Development

### Setup

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

```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 = {Nishide, Takumi},
  year = {2026},
  url = {https://github.com/your-username/pyg-hyper}
}
```
