Metadata-Version: 2.4
Name: qinglong-score
Version: 0.2.1
Summary: Contract-first differentiable image scoring adapters
Project-URL: Homepage, https://github.com/sdbds/qinglong-score
Project-URL: Repository, https://github.com/sdbds/qinglong-score
Project-URL: Issues, https://github.com/sdbds/qinglong-score/issues
Author-email: sdbds <8085926+sdbds@users.noreply.github.com>
License-Expression: AGPL-3.0-only
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: aesthetic-scoring,differentiable,image-reward,pytorch,reward-model
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.10
Requires-Dist: einops<1,>=0.8
Requires-Dist: ftfy==6.3.1
Requires-Dist: huggingface-hub[hf-xet]<1,>=0.36
Requires-Dist: numpy<3,>=2
Requires-Dist: regex==2026.7.19
Requires-Dist: safetensors<1,>=0.7
Requires-Dist: torch<2.14,>=2.13
Requires-Dist: torchvision<0.29,>=0.28
Requires-Dist: transformers<4.58,>=4.57.1
Provides-Extra: test
Requires-Dist: mypy<2,>=1.15; extra == 'test'
Requires-Dist: pytest<9,>=8.3; extra == 'test'
Requires-Dist: ruff<1,>=0.9; extra == 'test'
Requires-Dist: tomli<3,>=2.2; (python_version < '3.11') and extra == 'test'
Description-Content-Type: text/markdown

# Qinglong Score

Qinglong Score is inspired by the original
[imscore](https://github.com/RE-N-Y/imscore) project.

Qinglong Score is a contract-first PyTorch interface for image reward and
aesthetic scorers. `load_scorer()` returns the typed public `Scorer` interface;
it accepts image tensors, distinguishes exact autograd from an explicitly
declared surrogate, and returns exactly one score per sample.

All six `0.1.0` scorers have real-checkpoint Windows and Linux evidence,
including applicable legacy and Transformers endpoint gates. HPSv3 additionally
has explicit FlashAttention 2 and SDPA score, batch-isolation, and input-gradient
evidence on both platforms. Version `0.2.0` added CycleReward, HPSv3++, and three
UniPercept views. HPSv3++ and the UniPercept views are now stable Registry
entries; HPSv3++ retains its official surrogate-gradient classification and
UniPercept remains evaluation-only.

## Install

Package installation, clean import, and the offline contract are tested on
Python 3.10 through 3.13 on both Linux and Windows. Real-checkpoint Windows GPU
qualification remains Python 3.11 only, as does the supported Windows
FlashAttention wheel.

From PyPI:

```console
python -m pip install qinglong-score
```

From a checkout:

```console
python -m pip install .
```

There are no model or experimental runtime extras. HPSv2 uses a finite private
model and tokenizer runtime rather than an installed OpenCLIP distribution. Its
exact `ftfy==6.3.1` and `regex==2026.7.19` requirements are part of the score
definition. They can make an environment with incompatible dependency
requirements unresolvable; use a dedicated environment rather than overriding
the resolver or installing with `--no-deps`. The default V2.5 checkpoint
downloads its independently pinned SigLIP backbone and predictor head on first
load.

## Quick Start

```python
import torch

from qinglong_score import get_scorer_spec, load_scorer

spec = get_scorer_spec("aesthetic_predictor_v2_5")
assert spec.gradient_kind == "exact"

scorer = load_scorer(
    "aesthetic_predictor_v2_5",
    device="cuda",
    dtype=torch.float16,
    gradient_requirement="exact",
)
print(scorer.checkpoint_identity)

images = torch.rand(
    2,
    3,
    768,
    512,
    device=scorer.device,
    dtype=scorer.input_dtype,
    requires_grad=True,
)
scores = scorer.score(images)
assert scores.shape == (2,)
scores.mean().backward()
assert images.grad is not None
```

`gradient_requirement` rejects an unsuitable registered gradient kind before
device probing or checkpoint download. `scorer.checkpoint_identity` records the
exact remote checkpoint row, or the path and format of an explicitly supplied
local checkpoint, so experiment logs can distinguish numerically different
weights.

The public image contract is strict: `[B, 3, H, W]` with positive dimensions,
floating point, finite, within `1e-6` of `[0, 1]`, on `scorer.device`, and
exactly `scorer.input_dtype`; the output is exactly `[B]`. Model-specific shape
limits are documented by the owning Adapter rather than imposed on unrelated
scorers.
The boundary tolerance only avoids rejecting floating-point roundoff. Qinglong
Score does not silently clamp, cast, rescale, or move input, including tolerated
boundary values.
Loaded scorers reject post-load transforms that would change or copy their
parameters, plus `.train()` and `.requires_grad_(True)`; call `load_scorer()`
again for a different runtime configuration. A true device/dtype no-op remains
valid, so a scorer loaded on the final device can safely live inside a parent
module later moved to that same configuration.

## Discovery

```python
from qinglong_score import get_scorer_spec, list_scorers

print(list_scorers())
print(get_scorer_spec("aesthetic_predictor_v2_5"))
```

The registry is closed for each release; public `ScorerSpec` metadata does not
expose factories, and unavailable models do not receive stubs that only raise
at runtime.

| Scorer | Status | Prompts | Gradient kind |
| --- | --- | --- | --- |
| `aesthetic_predictor_v2_5` | stable Windows/Linux reference | no | exact |
| `aesthetic_siglip` | stable Windows/Linux reference | no | surrogate, straight-through Pillow resize |
| `cycle_reward` | stable Windows/Linux Combo, I2T, and T2I references | yes | exact |
| `pickscore` | stable Windows/Linux official and imscore reference | yes | exact |
| `hpsv2` | stable Windows/Linux official and imscore reference | yes | exact |
| `image_reward` | stable Windows/Linux official and imscore reference | yes | exact |
| `hpsv3` | stable Windows/Linux FA2 and SDPA reference | yes | exact |
| `hpsv3_plus_plus` | stable lossless BF16 row; accepted limitations documented | yes | surrogate, official capability stop-gradient |
| `unipercept_iaa` | stable; evaluation only | no | none |
| `unipercept_iqa` | stable; evaluation only | no | none |
| `unipercept_ista` | stable; evaluation only | no | none |

## 0.2.1 Runtime Cleanup

Version `0.2.1` removes the external OpenCLIP and Timm runtime distributions.
HPSv2 now owns its fixed ViT-H/14 graph, tokenizer, and verified BPE asset;
UniPercept uses a separately attributed private DropPath subset. The four
approved stability changes are guarded against the frozen `v0.2.0` Registry
metadata, so checkpoints, dtypes, gradient kinds, and backend preferences cannot
move with the status change. The promotion decision retains unexecuted platform
and backend checks as accepted limitations rather than reporting them as
passing evidence. The HPSv2 migration passed bit-exact CPU comparison and the
official/legacy CUDA gates on Windows and Linux; see the
[0.2.1 release notes](docs/releases/0.2.1.md),
[runtime evidence](docs/evidence/0.2.1/hpsv2-vendored-runtime-windows.json), and
[stability promotion record](docs/evidence/0.2.1/stability-promotions.json).

## 0.2.0 Release

CycleReward is the admitted second-batch family: Combo is the default, I2T and
T2I are explicit checkpoint rows, and all three passed pinned official-reference,
batch, exact-gradient, Windows, and Linux gates. Version `0.2.0` also adds exact
checkpoint identity, gradient-kind preflight, the public `convrot8` format
family, an offline audited HPSv3++ pickle-to-safetensors converter, and the thin
`hpsv3_plus_plus` runtime backed by the published four-shard BF16 checkpoint.
It also registers `unipercept_iaa`, `unipercept_iqa`, and `unipercept_ista`
against pinned checkpoint artifacts. Those scorers share the official
101-token score definition but
load independent model instances and explicitly declare `gradient_kind="none"`.

SpectraReward remains absent from the Registry: it produced connected gradients
on FA2 and SDPA but no common epsilon passed the frozen exact directional gate.
HPSv3++ loaded and backpropagated on FA2, but its official capability encoder
detaches an image-dependent branch, so the registered scorer declares
`gradient_kind="surrogate"` rather than `"exact"`. The pinned UniPercept
artifacts passed identity, tokenizer, architecture, Tensor-preprocessing, and
Windows runtime/isolation checks. Current stable classifications and their
accepted limitations are recorded without manufacturing additional gates.
Failed candidates still receive no placeholder factories.

See [the public contract](docs/contracts.md), the
[V2.5 model evidence](docs/models/aesthetic_predictor_v2_5.md),
[AestheticSigLIP evidence](docs/models/aesthetic_siglip.md),
[PickScore evidence](docs/models/pickscore.md),
[HPSv2 evidence](docs/models/hpsv2.md),
[ImageReward evidence](docs/models/image_reward.md),
[CycleReward evidence](docs/models/cycle_reward.md),
[SpectraReward exclusion evidence](docs/models/spectra_reward.md),
[UniPercept evidence](docs/models/unipercept.md),
[HPSv3++ runtime evidence](docs/models/hpsv3_plus_plus.md),
[HPSv3 evidence](docs/models/hpsv3.md), and the
[migration guide](docs/migration-from-imscore.md). Cross-platform test and clean
distribution evidence is recorded in
[the release matrix](docs/evidence/release-matrix.json). The frozen `0.1.0`
criteria remain mapped in [their evidence index](docs/evidence/acceptance-criteria.json),
and the 25 `0.2.0` criteria are mapped in
[the 0.2.0 evidence index](docs/evidence/0.2.0/acceptance-criteria.json). The
complete approved expansion design is recorded in
[the 0.2.0 design specification](docs/superpowers/specs/2026-08-05-qinglong-score-0.2.0-model-expansion-design.md).
See the [0.2.1 release notes](docs/releases/0.2.1.md) for the current runtime and
stability changes, and the [0.2.0 release notes](docs/releases/0.2.0.md) for the
earlier compatibility and candidate decisions. Maintainers should follow the
[release process](docs/releasing.md) for the tag-to-PyPI Trusted Publishing path.

## Quality Benchmarks

The committed HPSv3++ BF16-versus-ConvRot8 evaluation covers 10,185 official
preference pairs, with split results, score and margin errors, correlations, and
the component-ablation study recorded in the
[quality benchmark results](docs/benchmarks.md). Runtime smoke checks and
platform qualification are deliberately kept out of that report.

## License

Qinglong Score is licensed under AGPL-3.0-only. Vendored and derived upstream
components retain their own notices in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## Citations

`aesthetic_predictor_v2_5` uses the SigLIP backbone paper:

```bibtex
@misc{zhai2023sigmoidlosslanguageimage,
  title = {Sigmoid Loss for Language Image Pre-Training},
  author = {Xiaohua Zhai and Basil Mustafa and Alexander Kolesnikov and Lucas Beyer},
  year = {2023},
  eprint = {2303.15343},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2303.15343}
}
```

`aesthetic_siglip` uses the SigLIP 2 paper:

```bibtex
@misc{tschannen2025siglip2multilingualvisionlanguage,
  title = {SigLIP 2: Multilingual Vision-Language Encoders with Improved Semantic Understanding, Localization, and Dense Features},
  author = {Michael Tschannen and Alexey Gritsenko and Xiao Wang and Muhammad Ferjad Naeem and Ibrahim Alabdulmohsin and Nikhil Parthasarathy and Talfan Evans and Lucas Beyer and Ye Xia and Basil Mustafa and Olivier H{\'e}naff and Jeremiah Harmsen and Andreas Steiner and Xiaohua Zhai},
  year = {2025},
  eprint = {2502.14786},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2502.14786}
}
```

`cycle_reward` uses the CycleReward paper:

```bibtex
@misc{bahng2025cycleconsistencyrewardlearning,
  title = {Cycle Consistency as Reward: Learning Image-Text Alignment without Human Preferences},
  author = {Hyojin Bahng and Caroline Chan and Fredo Durand and Phillip Isola},
  year = {2025},
  eprint = {2506.02095},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2506.02095}
}
```

`pickscore` uses the Pick-a-Pic paper:

```bibtex
@misc{kirstain2023pickapicopendatasetuser,
  title = {Pick-a-Pic: An Open Dataset of User Preferences for Text-to-Image Generation},
  author = {Yuval Kirstain and Adam Polyak and Uriel Singer and Shahbuland Matiana and Joe Penna and Omer Levy},
  year = {2023},
  eprint = {2305.01569},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2305.01569}
}
```

`hpsv2` uses the HPSv2 paper:

```bibtex
@misc{wu2023humanpreferencescorev2,
  title = {Human Preference Score v2: A Solid Benchmark for Evaluating Human Preferences of Text-to-Image Synthesis},
  author = {Xiaoshi Wu and Yiming Hao and Keqiang Sun and Yixiong Chen and Feng Zhu and Rui Zhao and Hongsheng Li},
  year = {2023},
  eprint = {2306.09341},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2306.09341}
}
```

`image_reward` uses the ImageReward paper:

```bibtex
@misc{xu2023imagerewardlearningevaluatinghuman,
  title = {ImageReward: Learning and Evaluating Human Preferences for Text-to-Image Generation},
  author = {Jiazheng Xu and Xiao Liu and Yuchen Wu and Yuxuan Tong and Qinkai Li and Ming Ding and Jie Tang and Yuxiao Dong},
  year = {2023},
  eprint = {2304.05977},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2304.05977}
}
```

`hpsv3` uses the HPSv3 paper:

```bibtex
@misc{ma2025hpsv3widespectrumhumanpreference,
  title = {HPSv3: Towards Wide-Spectrum Human Preference Score},
  author = {Yuhang Ma and Yunhao Shui and Xiaoshi Wu and Keqiang Sun and Hongsheng Li},
  year = {2025},
  eprint = {2508.03789},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2508.03789}
}
```

`hpsv3_plus_plus` uses the HPSv3++ paper:

```bibtex
@misc{liu2026hpsv3scalingrewardmodels,
  title = {HPSv3++: Scaling Reward Models Across the Full Spectrum of Diffusion Model Capabilities},
  author = {Yijun Liu and Jie Huang and Zeyue Xue and Yuming Li and Ruizhe He and Haoran Li and Shijia Ge and Siming Fu},
  year = {2026},
  eprint = {2606.14657},
  archivePrefix = {arXiv},
  primaryClass = {cs.CV},
  url = {https://arxiv.org/abs/2606.14657}
}
```

`unipercept_iaa`, `unipercept_iqa`, and `unipercept_ista` share the UniPercept
paper:

    @misc{cao2025uniperceptunifiedperceptuallevelimage,
      title = {UniPercept: Towards Unified Perceptual-Level Image Understanding across Aesthetics, Quality, Structure, and Texture},
      author = {Shuo Cao and Jiayang Li and Xiaohui Li and Yuandong Pu and Kaiwen Zhu and Yuanting Gao and Siqi Luo and Yi Xin and Qi Qin and Yu Zhou and Xiangyu Chen and Wenlong Zhang and Bin Fu and Yu Qiao and Yihao Liu},
      year = {2025},
      eprint = {2512.21675},
      archivePrefix = {arXiv},
      primaryClass = {cs.CV},
      url = {https://arxiv.org/abs/2512.21675}
    }
