A Bayesian tool for discovering your true preferences
Product Picker is a general-purpose pairwise comparison tool. It helps you make decisions when faced with too many visual options. Whether you're choosing a vacation destination, an apartment, a color scheme, or (as in the origin story) the perfect piece of jewelry, this app uses Microsoft's TrueSkill algorithm to learn your subjective taste through simple "A or B" choices.
Read the full three-part series on how this works:
👉 Read the Blog Series (hosted on GitHub Pages)
- Part 1: The Pendant Problem — Motivation and why pairwise comparison beats absolute ratings.
-
Part 2: TrueSkill Demystified — How
$\mu$ (appeal) and$\sigma$ (uncertainty) model your taste. -
Part 3: The Pair Selection Puzzle — Active learning,
$E[\Delta\sigma]$ , and Thompson Sampling.
(Markdown source files are also available locally)
- 🖼️ Visual Discovery: Scans any folder of images (JPG, PNG, WEBP, etc.)
- 🎯 Preference Learning: Learns your taste through natural "Which do you like more?" choices.
- 📊 TrueSkill Algorithm: Bayesian rating system that tracks both what you like and how confident it is.
- 🏆 Stable Leaderboard: Uses Conservative Scores (
$\mu - 3\sigma$ ) to ensure top results are battle-tested favorites. - 📈 Active Learning: Intelligently picks pairs that teach the algorithm the most about your preferences.
- 💾 SQLite Persistence: Your rankings and match history are saved locally in the image folder.
# Clone the repository
git clone https://github.com/hugocool/product_picker.git
cd product_picker
# Install with uv (recommended)
uv sync
# Or with pip
python -m venv venv
source venv/bin/activate
pip install -r requirements.txtfrom product_picker.app import launch_app
# Launch the Gradio interface
launch_app()See notebooks/pendant_chooser.ipynb for an interactive notebook interface.
python -m product_picker
# With uv
uv run python -m product_picker
# Or activate venv first
source .venv/bin/activate # On Windows: .venv\Scripts\activate- Scan: Point to a folder containing product images
- Compare: Choose between pairs of images (Left/Right/Draw/Skip)
- Rank: TrueSkill updates ratings after each comparison
- View: Leaderboard shows top-ranked items with confidence scores
- Represents skill as N(μ, σ²) - a normal distribution with mean (μ) and uncertainty (σ)
- Conservative score = μ - 3σ (99.7% confidence lower bound)
- Prioritizes high-uncertainty items and close matchups for informative comparisons
- Penalizes repeated pair comparisons to avoid loops
- Database stored at
YOUR_FOLDER/.pendant_ranker/pendants.sqlite - Last used folder remembered at
~/.pendant_chooser/config.json - SHA-256 content hashing prevents duplicates
- Ratings persist across sessions
- Simply load the same folder to continue where you left off
product_picker/
├── src/product_picker/ # Core application code
├── blog/ # VitePress documentation site
├── docs/ # Technical documentation
│ ├── ALGORITHM.md # Pair selection algorithm details
│ ├── QUICKSTART.md # Installation & usage guide
│ └── FOLDER_PERSISTENCE.md # Persistence feature docs
├── notebooks/ # Jupyter notebooks
└── tests/ # Unit tests
- Blog Series: https://hugocool.github.io/product_picker/
- Quick Start: docs/QUICKSTART.md
- Algorithm Details: docs/ALGORITHM.md
MIT