Leaderboard and Ladder

Leaderboard and Ladder

You've joined the team behind the ranked mode of a casual online game. The leaderboard library keeps each player's best score and ranks players. Players have reported ranking oddities, and two features are queued: an Elo ladder for head-to-head matches, and seasons.

Codebase

How your code is run

The grader calls run(operations) from leaderboard/app.py and compares the list of results with the expected one: one result per operation, in order. Errors are strings starting with error:, never exceptions.

A board is a named leaderboard: "score" (default) and, from Part 2, "elo". Players with equal values on a board are *tied* and share a rank: the rank of a player is 1 plus the number of players with a strictly better value (so ranks run 1, 2, 2, 4).

Score board order: higher score first, then the earlier time of the best score, then player name ascending (plain string comparison). The elo board orders by rating descending, then name ascending.

Validation, in this order, where relevant: error: invalid player (not a non-empty string), error: invalid score (integers of at least 0 only; booleans and floats are invalid), error: invalid timestamp (integer of at least 0), error: time went backwards (the clock is shared by every operation that takes a timestamp and never decreases; equal is fine). rank/around: player, then error: unknown board 'x'. top: error: invalid n (integer of at least 1), then board. Wrong argument count: error: bad arguments for 'name'; unknown name: error: unknown operation 'name'; not a non-empty list starting with a string: error: malformed operation.

Example:

[["submit", "amy", 900, 1], ["submit", "bob", 800, 2], ["submit", "cat", 800, 3], ["top", 3]]

returns [900, 800, 800, [{"rank": 1, "player": "amy", "score": 900}, {"rank": 2, "player": "bob", "score": 800}, {"rank": 2, "player": "cat", "score": 800}]].

Part 1 — Rank oddities

Goal: Ranks and orderings on the score board must be consistent.

Players report: "I'm tied for second but the leaderboard says I'm fourth when I search for myself" is fine, but "the player after the tie shows a different rank in rank than on the top list", and "players with identical scores and times appear in a different order every deploy".

Rules

1. rank and top (and around) always agree, and both use the ranking rule above.
2. Players with the same score are ordered by the time of their best score (earlier first), then by name ascending.
3. All other behaviour stays as described.

Example: scores amy 900, bob 800, cat 800, dan 700 give ranks 1, 2, 2, 4, and ["rank", "dan"] is 4.

Part 2 — Elo ladder (LB-61)

Goal: Rate players from head-to-head matches.

["match", a, b, result, ts] with result one of "a" (first player won), "b" (second player won) or "draw". It returns {"a": new_rating_a, "b": new_rating_b}. Players are created on their first match with rating 1000. ["rating", player] returns the rating, or null for a player who has never played a match. The "elo" board accepts rank, top, around.

Rules

1. Let E_a = 1 / (1 + 10 ** ((R_b - R_a) / 400)) and E_b = 1 - E_a, with R_a, R_b the ratings *before* the match. The score S of a player is 1 for a win, 0 for a loss, 0.5 for a draw.
2. New rating = floor(R + K * (S - E) + 0.5) for each player (round to nearest, halves up). Each player has their own K: K_PROVISIONAL (32) while they have played fewer than PROVISIONAL_GAMES (10) matches before this one, otherwise K_ESTABLISHED (16). Both are in config.py.
3. Both players' number of matches goes up by one after every valid match, including draws. A player's matches in profile counts them too.
4. Errors, in order: error: invalid player (a, then b), error: same player, error: invalid result, then the timestamp errors. Nothing changes on an error.
5. Matches never touch the score board, and submissions never touch ratings.

Example: two fresh players: ["match", "ann", "bea", "a", 10] gives {"a": 1016, "b": 984}. Then ["match", "ann", "cy", "a", 20] gives {"a": 1031, "b": 985}.

Part 3 — Seasons (LB-88)

Goal: Reset the ladder periodically and keep the past available.

Rules

1. end_season freezes the current score board and elo board exactly as they are, including ranks and ties. Later play never changes a finished season.
2. Then the score board is emptied. Ratings are kept but pulled towards the start: new = floor(1000 + (R - 1000) * SEASON_CARRY + 0.5) (SEASON_CARRY is 0.5 in config.py, halves round up), and every player's match count restarts at 0, so everyone is provisional again.
3. profile is lifetime data and is not reset.
4. A season may be empty. end_season takes part in the clock: its ts must not be earlier than the last timestamp seen.
5. Everything from Parts 1 and 2 behaves as before inside a new season.

Example: scores amy 900, bob 700, cat 900; ["end_season", 4] is 1; then ["top", 3] is [] and ["season_top", 1, 3] lists amy and cat at rank 1 and bob at rank 3.

Notes

• clock.py, players.py and app.py have been in production for a while; so has the read side of ratings.py.
• You may use the AI assistant freely. Later parts must not break earlier ones; the visible tests are a starting point, not the full suite.
• Completing all three parts is a strong result.