Metadata-Version: 2.4
Name: pu-toolbox
Version: 1.0.0
Summary: Positive-Unlabeled Learning Python Toolbox — sklearn-compatible
Project-URL: Repository, https://github.com/shuidisjtu/pu-learning-toolbox
Author: shuidisjtu
License: MIT License
        
        Copyright (c) 2026 shuidisjtu
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECT WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: machine-learning,positive-unlabeled,pu-learning,scikit-learn
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Provides-Extra: all
Requires-Dist: densratio==0.3.0; extra == 'all'
Requires-Dist: lightning>=2.0; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Requires-Dist: torchvision>=0.15; extra == 'all'
Requires-Dist: tqdm>=4.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
Provides-Extra: research
Requires-Dist: densratio==0.3.0; extra == 'research'
Requires-Dist: lightning>=2.0; extra == 'research'
Requires-Dist: torch>=2.0; extra == 'research'
Requires-Dist: torchvision>=0.15; extra == 'research'
Requires-Dist: tqdm>=4.0; extra == 'research'
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == 'torch'
Description-Content-Type: text/markdown

[English](README.md) | [中文](README.zh-CN.md)

# PU Learning Toolbox

**Positive-Unlabeled learning in Python** -- sklearn-compatible API, 17 research paper methods, SCAR & SAR support.

![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)
![Status](https://img.shields.io/badge/status-1.0.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## Features

- **17 algorithms** from recent PU learning research, all native clean-room implementations ([method cards](docs/research/method_cards/))
- **sklearn-compatible API** -- `fit(X, y)` / `predict(X)` / `decision_function(X)`, works with pipelines and cross-validation
- **SCAR & SAR** -- constant and instance-dependent labeling mechanisms, with a data simulator
- **Data profiling + recommender** -- automatic quality checks, SCAR/SAR evidence, and a 7-dimension scoring recommender that picks the method for your data
- **Auditable pipeline** -- one-call `PUPipeline` (profile -> prior -> train -> PU-stratified CV -> evaluate) plus structured diagnostic reports and prior/propensity sensitivity analysis
- **CLI** -- `pu-toolbox` turns the whole pipeline into terminal commands

## Quick Start

> **Note**: Not yet published on PyPI. Install from source.

```bash
git clone https://github.com/shuidisjtu/pu-learning-toolbox.git
cd pu-learning-toolbox
pip install -e .          # core dependencies
pip install -e ".[torch]" # + PyTorch-based methods (nnPU, Dist-PU, Self-PU, ...)
```

### Installation environments

Any Python interpreter >= 3.10 works: the package is a pure-Python universal
wheel with no compiled extensions, so the interpreter source does not matter.
Notes per environment:

- **venv / uv** (recommended): standard isolated environments, nothing special.
- **System Python** (python.org / Ubuntu / Homebrew): must be >= 3.10.
  Ubuntu 22.04+ and Debian 12+ block `pip install` into the system environment
  (PEP 668) -- create a venv instead.
- **Anaconda / Miniconda**: `pip install pu-toolbox` inside a conda env
  (the package is PyPI-only; `conda install` will not find it). If you already
  installed torch via conda, a plain `pip install pu-toolbox` (without the
  `[torch]` extra) still enables the PyTorch-based methods -- torch is an
  optional dependency loaded lazily.

### Hello World

```python
import numpy as np
from pu_toolbox.preprocessing import make_sar_dataset
from pu_toolbox import PUPipeline

# Synthetic PU data: some positives are labeled (1), rest are unlabeled (0)
X, y_pu, y_true, _ = make_sar_dataset(
    n_samples=1000, n_features=8, class_prior=0.3, random_state=42,
)

# One call: profile -> class prior -> train -> PU-stratified CV -> evaluate
report = PUPipeline().fit_evaluate(X, y_pu, y_true=y_true)
print(report.summary())
```

Full docs (Chinese): [docs/README.md](docs/README.md). More runnable examples: [`examples/minimal/`](examples/minimal/).

## Command Line

The `pu-toolbox` console command wraps the full pipeline. Full guide: [`docs/user/howto/cli.md`](docs/user/howto/cli.md).

```bash
# 1. Generate SCAR demo data (X.csv / y_pu.csv / y_true.csv)
pu-toolbox make-demo-data --out-dir demo/ --n 200 --seed 42

# 2. One-shot full pipeline run (auto mode picks the algorithm)
pu-toolbox run --data demo/X.csv --labels demo/y_pu.csv --out-dir results/

# 3. Inspect results
#    results/report.md     full Markdown report
#    results/report.json   strict JSON (no NaN), machine-readable
```

## Documentation

Docs are split by audience; the full index is [`docs/README.md`](docs/README.md).

| Entry | Content |
|----------|---------|
| [`docs/user/quickstart.md`](docs/user/quickstart.md) | 5-minute start (CLI + Python) |
| [`docs/user/concepts/`](docs/user/concepts/) | PU problem, SCAR/SAR, method selection |
| [`docs/user/howto/`](docs/user/howto/) | Task guides: simulation, profiling, pipeline, CLI, reports, sensitivity |
| [`docs/user/reference/api.md`](docs/user/reference/api.md) | Precise API contract |
| [`docs/dev/`](docs/dev/) | Contributor docs: architecture, structure, roadmap, compatibility |
| [`docs/research/method_cards/`](docs/research/method_cards/) | Per-paper research cards |

## AI workflow skill

`pu-workflow` (Agent Skills open standard) drives the full PU analysis
workflow — profiling, assumption diagnosis, method recommendation,
training, and result interpretation — from natural language. Loaded
natively by Claude Code / Cursor (`.claude/skills/`) and Codex / Gemini
CLI / Windsurf (`.agents/skills/`).

## Development

```bash
uv run pytest tests/ -v -m "not slow and not e2e"   # fast tests (e2e runs nightly)
uv run ruff check pu_toolbox/               # lint
uv run ruff format --check pu_toolbox/      # format check

# Quality gates
uv run python scripts/check_test_quality.py
uv run python scripts/check_doc_links.py
uv run python scripts/check_project_metadata.py
uv run python scripts/check_math_rendering.py
uv run python scripts/check_skill_sync.py
uv run python scripts/check_format.py        # ruff check + format --check (full scope)
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution guidelines.

## License

MIT
