3.6 KiB
Single Poker Hand Ranking Service
This project started as a take-home interview task for an MLOps Engineer role. It is a very simple calculation I've wildly overengineered into a demonstration of how I go about building APIs.
Project Scope
This service comprises an API to compute the rank of an individual poker hand. The scope of this project is to:
- Write an algorithm that takes a hand of cards and identifies the ranking of the given hand.
- Expose an API to serve this algorithm via an endpoint
/rank, that accepts a valid poker hand and returns its ranking. - Rank information should be formatted as
<rank_name>: <description>, see description format for each different rank below.
Poker Rules
A poker hand consists of 5 cards dealt from a deck. A deck is composed of 52 cards ordered as 2 through 10, J (Jack), Q (Queen), K (King), and A (Ace); and split across 4 suits: ♠ Spades (black), ♦ Diamonds (red), ♣ Clubs (black), and ♥ Hearts (red).
Poker hands are ranked by the following partial order from highest to lowest:
1. Royal Flush ~ [ A♥ K♥ Q♥ J♥ 10♥ ]
The best hand possible, a royal flush consists of A, K, Q, J and 10, all of the same suit.
Description format: <suit>
2. Straight Flush ~ [ 6♥ 7♥ 8♥ 9♥ 10♥ ]
Also very rare, a straight flush consists of any straight that is all the same suit. Note Ace can act as value 1 to form a straight with values 2 3 4 5.
Description format: <highest_value>-high <suit>
3. Four of a Kind ~ [ A♥ A♣ A♦ A♠ K♥ ]
Four of a kind, or 'quads', consists of four cards of equal value along with another card known as a side card.
Description format: <quads value>
4. Full House ~ [ A♥ A♣ A♦ K♠ K♥ ]
A full house consists of three cards of one value and two cards of another.
Description format: <trips_value> over <pair_value>
5. FLush ~ [ K♣ 10♣ 8♣ 7♣ 5♣ ]
A flush is a hand which has all cards of the same suit.
Description format: <suit>
6. Straight ~ [ 10♥ 9♣ 8♦ 7♠ 6♥ ]
A straight has five cards of consecutive value that are not all the same suit. Note Ace can act as value 1 to form a straight with values 2 3 4 5.
Description format: <highest_value>-high
7. Three of a Kind ~ [ A♥ A♣ A♦ K♠ Q♥ ]
Also known as 'trips', three of a kind is 3 cards of the same value and 2 side cards of different values.
Description format: <trips value>
8. Two Pair ~ [ A♥ A♣ K♦ K♠ 7♥ ]
Two pair cosists of two cards of the same value, and three extra cards.
Description format: <high_pair_value> and <low_pair_value>
9. Pair ~ [ A♥ A♣ K♦ J♠ 7♥ ]
One pair consists of two cards of the same value, and three extra cards.
Description format: <pair_value>
10. High Card ~ [ A♥ K♣ Q♦ 9♠ 7♥ ]
Five cards that do not interact with each other to make any of the above hands.
Description format: <value>
Examples
Query: "2H 3D 5S 9C KD"
Result: "high card: King"
~
Query: "2H 4D 4S 2C 4H"
Result: "full house: 4 over 2"
~
Query: "6H 7H 8H 9H 10H"
Result: "straight flush: 10-high diamonds"
Requirements
Usage
- Install with
make install. - Run linting and tests with
make quality test coverage clean. - Build the API container with
make build, then run API withdocker compose up -d. - Check API health with
curl localhost:8000 - Query API for rank with e.g.
curl -X POST -d '2H 3D 5S 10C KD' localhost:8000/rank