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:

pip install librehps

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.

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 falls back to stock Qwen3.5 attention when FA4 isn't available — but training does require it. Build instructions are in docs/INSTALL.md.

Repository layout

Path	Contents
librehps/	The Python package (model, dataset, training, inference, evaluation).
docs/	Architecture and design documents. docs/PLAN.md is the top-level project plan; docs/DATA_PROVENANCE.md is the dataset audit.
scripts/	CLI tools — index builder, dataset downloaders, release bundler, benchmark runners.
tests/	Test suite. Most tests run on CPU; integration tests are gated behind LIBREHPS_INTEGRATION_* env vars.
reports/	Evaluation outputs from past training and benchmark runs.
release/	Per-version release directories. The current production release is 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.
• Model weights: Apache-2.0.
• Training data: permissive union (MIT / Apache-2.0 / BSD-3-Clause / CDLA-Permissive-2.0). See 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