Quickstart

Install, run, vote

From pip install to a live leaderboard in about ten minutes. SQLite by default — no database to set up.

Install

compere needs Python 3.11 or newer.

# from PyPI
pip install compere

# or with uv
uv add compere

Run the service

The server persists to SQLite by default. Set DATABASE_URL to point at PostgreSQL instead.

compere --port 8090
# -> Uvicorn running on http://127.0.0.1:8090
# -> interactive OpenAPI docs at http://127.0.0.1:8090/docs

Register entities

Add the things you want to rank.

curl -X POST localhost:8090/entities/ \
  -H "Content-Type: application/json" \
  -d '{"name": "headline-a"}'

curl -X POST localhost:8090/entities/ \
  -d '{"name": "headline-b"}'

4
Ask UCB for the next pair

The bandit returns the matchup whose outcome is most uncertain — the one that will move the ranking most.
```
curl localhost:8090/mab/next_comparison
# {"entity1_id": 1, "entity2_id": 2}
```

Record verdicts, read ratings

Each verdict updates Elo (K = 32, initial 1500). The leaderboard is a pure function of the votes.

# record the winner of that pair
curl -X POST localhost:8090/comparisons/ \
  -H "Content-Type: application/json" \
  -d '{"entity1_id":1,"entity2_id":2,"selected_entity_id":1}'

# read the leaderboard, sorted by Elo
curl localhost:8090/ratings

Prefer no server? Use it as a library

Import the modules directly for offline studies and notebooks.

from compere.modules import entity, comparison, rating

a = entity.create_entity(name="design-a")
b = entity.create_entity(name="design-b")
comparison.create_comparison(
    entity1_id=a.id, entity2_id=b.id, selected_entity_id=a.id,
)
for r in rating.get_ratings():
    print(r.name, r.rating)

Full documentation → Understand the algorithms