Metadata-Version: 2.4
Name: librehps
Version: 1.1.1
Summary: LibreHPS — permissively-licensed human preference reward model for text-to-image and text-to-video generation.
Project-URL: Homepage, https://spacecruft.org/movies/LibreHPS
Project-URL: Repository, https://spacecruft.org/movies/LibreHPS
Project-URL: Documentation, https://spacecruft.org/movies/LibreHPS/src/branch/main/docs/PLAN.md
Author: LibreHPS contributors
License-Expression: MIT
License-File: LICENSE
Keywords: flash-attention,human-preference,qwen3.5,qwen3.6,reward-model,rlhf,text-to-image,text-to-video
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.12
Requires-Dist: accelerate>=1.10
Requires-Dist: av>=15
Requires-Dist: datasets>=4.2
Requires-Dist: deepspeed>=0.18
Requires-Dist: fire>=0.7
Requires-Dist: huggingface-hub>=0.36
Requires-Dist: loguru>=0.7
Requires-Dist: numpy<3,>=2.1
Requires-Dist: opencv-python>=4.12
Requires-Dist: pandas>=2.3
Requires-Dist: peft>=0.18
Requires-Dist: pillow>=11
Requires-Dist: pyarrow>=20
Requires-Dist: pyyaml>=6.0
Requires-Dist: safetensors>=0.6
Requires-Dist: scipy>=1.14
Requires-Dist: sentencepiece>=0.2
Requires-Dist: tokenizers>=0.22
Requires-Dist: torchcodec>=0.11
Requires-Dist: tqdm>=4.67
Requires-Dist: transformers==5.5.4
Requires-Dist: trl==1.2.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Description-Content-Type: text/markdown

# LibreHPS

LibreHPS is a permissively-licensed reward model for text-to-image and
text-to-video generation. It looks at a generated image or short video
and a text prompt and predicts how a human reviewer would rate the
match — useful for picking the best of N samples, training another
generator with reinforcement learning from feedback, or running an
automated benchmark.

This is the source-code repository. The trained model weights live on
Hugging Face: **`LibreHPS/LibreHPS-4B-v1.1`**.

## Install

To use the model:

```bash
pip install librehps
```

```python
from librehps import LibreHPS

scorer = LibreHPS.from_pretrained("LibreHPS/LibreHPS-4B-v1.1")
result = scorer.score_image(image="photo.png", prompt="a cat sitting on a windowsill")
print(result.overall.mean)
```

By default the loader uses Flash Attention 4 on CUDA Blackwell when
available, and falls back to stock attention (SDPA / eager) on any
other CUDA / CPU / MPS device. See the model card on Hugging Face for
the full inference surface, including pair-wise comparison with
calibrated probabilities.

## Develop from source

Python 3.12 is required.

```bash
pyenv local 3.12
python -m venv venv
. venv/bin/activate
pip install -U pip setuptools wheel
pip install torch==2.11.0+cu130 torchvision torchaudio \
    --index-url https://download.pytorch.org/whl/cu130
pip install -e '.[dev]'
pytest
```

Flash Attention 4 is built from source for the fastest training /
inference on Blackwell (sm_100). It is NOT required for inference —
[`librehps/inference.py`](librehps/inference.py) falls back to stock
Qwen3.5 attention when FA4 isn't available — but training does require
it. Build instructions are in [`docs/INSTALL.md`](docs/INSTALL.md).

## Repository layout

| Path | Contents |
|---|---|
| [`librehps/`](librehps/) | The Python package (model, dataset, training, inference, evaluation). |
| [`docs/`](docs/) | Architecture and design documents. [`docs/PLAN.md`](docs/PLAN.md) is the top-level project plan; [`docs/DATA_PROVENANCE.md`](docs/DATA_PROVENANCE.md) is the dataset audit. |
| [`scripts/`](scripts/) | CLI tools — index builder, dataset downloaders, release bundler, benchmark runners. |
| [`tests/`](tests/) | Test suite. Most tests run on CPU; integration tests are gated behind `LIBREHPS_INTEGRATION_*` env vars. |
| [`reports/`](reports/) | Evaluation outputs from past training and benchmark runs. |
| [`release/`](release/) | Per-version release directories. The current production release is [`release/LibreHPS-4B-v1.1/`](release/LibreHPS-4B-v1.1/), which is what gets uploaded to Hugging Face. |

## Acknowledgement

LibreHPS is inspired by and architecturally influenced by **HPSv3**
(Ma, Shui, Wu, Sun, Li — ICCV 2025). LibreHPS is a from-scratch
reimplementation with a different backbone, training stack, and
permissively-licensed training data mix.

# License
- **Source code:** [MIT](LICENSE).
- **Model weights:** [Apache-2.0](docs/LICENSE-WEIGHTS).
- **Training data:** permissive union (MIT / Apache-2.0 / BSD-3-Clause / CDLA-Permissive-2.0). See [`docs/DATA_PROVENANCE.md`](docs/DATA_PROVENANCE.md) for the per-dataset audit and the per-image generator-redistribution audit applied to filter the training mix.

*Copyright © 2026 Jeff Moe.*

Loveland, Colorado, USA
