hand_classifier

Your mission

You've just joined PokerSolver Inc. as a new intern. It's day two of your first week, and your manager has slid a task onto your desk: "We need a hand-classifier for the wild-card module. The engine already has a shared library with the types and constants you'll need. Your starter file has the signature. Get classify passing and we can plug it into the solver. Don't touch the library; the other teams are using it."

Your checklist

• The engine supports a joker variant of five-card poker, where one or more cards in the hand can be wild. With a joker, the same five cards can often be read as several different hand categories, and the engine's house-rules table lets different rule-sets decide which ones are worth more. Your job is to pick the best-legal interpretation. This classifier will later feed Monte Carlo simulators.
• Merge category_ranks over DEFAULT_CATEGORY_RANKS so every category has a value ({**DEFAULT_CATEGORY_RANKS, **category_ranks} when supplied).
• Split the hand into real cards and jokers. A joker is any card with suit == Suit.JOKER; its rank is ignored.
• 0 jokers: evaluate the five real cards directly.
• 4 or 5 jokers: every category is reachable; return the max under your key.
• 1 to 3 jokers: enumerate rank assignments and evaluate each.
• Jokers may duplicate real cards, that's how FIVE_OF_A_KIND becomes reachable.
• Only FLUSH / STRAIGHT_FLUSH depend on suits, so you don't need a full 52ᵏ enumeration. One "break flush" and one "make flush" pattern per rank assignment suffices.
• Tie-break with key = lambda c: (category_ranks[c], DEFAULT_CATEGORY_RANKS[c]) so a custom-values tie resolves to the higher standard-poker hand.