Features
Everything a comparison study needs
Selection, rating, storage, and an HTTP surface — one cohesive package, not a pile of scripts.
Pair selection
Deciding which pair to ask about next — the part most Elo libraries leave to you.
UCB1 pair selection
A multi-armed bandit picks the next pair to compare, concentrating votes on uncertain matchups instead of asking about obvious ones. Exploration constant c = 1.414 by default.
Similarity pairing (alternative)
A second strategy pairs similar entities instead of UCB-optimal ones, exposed at /comparisons/next. Swap the selection policy without touching the rating layer.
Rating & ranking
Turning binary verdicts into an interpretable, sortable leaderboard.
Elo rating updates
The same Elo math you know from chess. K = 32 and initial rating 1500 by default, both configurable. Nothing fancier is claimed — you can explain any rating change in two sentences.
Sortable leaderboard
GET /ratings returns entities ordered by Elo. The board is a pure function of the votes it received — replayable and auditable, not a black box.
Service & library
Run it as a FastAPI server or import it as a plain Python library.
FastAPI HTTP service
Eleven endpoints for entities, comparisons, pair selection, ratings, and health. Interactive OpenAPI docs are served at /docs the moment you run compere.
Use it as a library
Skip the server entirely. Import create_entity, create_comparison, and get_ratings from compere.modules for offline studies and notebooks.
Persistence & operations
Storage, auth, and deployment knobs — sensible defaults, off unless you need them.
SQLite or PostgreSQL
SQLAlchemy persistence: SQLite by default (sqlite:///./compere.db), PostgreSQL via DATABASE_URL when you outgrow it. Same code on either.
Auth, CORS & rate limits
Optional JWT auth (AUTH_ENABLED), configurable CORS origins, and request rate limiting — all off by default so the happy path stays simple.
Docker-ready
A Dockerfile and docker-compose.yml ship in the repository. Container handles entities, comparisons, pair selection, and ratings as one cohesive service.
The HTTP surface — 11 endpoints
All visible in the interactive OpenAPI docs at /docs when the service is running.
| Method | Endpoint | Description |
|---|---|---|
| POST | /entities/ | Create an entity |
| GET | /entities/ | List entities (search, pagination) |
| GET | /entities/{id} | Get one entity |
| PUT | /entities/{id} | Update an entity |
| DELETE | /entities/{id} | Delete an entity |
| GET | /mab/next_comparison | Next pair via UCB1 |
| GET | /comparisons/next | Next pair via similarity |
| POST | /comparisons/ | Record a comparison result |
| GET | /comparisons/ | List comparison history |
| GET | /ratings | Leaderboard, sorted by Elo |
| GET | /health, /health/ready | Health & readiness |