pokerkit-plus 0.0.1__tar.gz

pokerkit_plus-0.0.1/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+.gstack/
+
+# Internal planning docs (reference private projects; kept local, not published)
+docs/SEMANTIC_LAYER_PLAN.md

pokerkit_plus-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 billcheung10
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pokerkit_plus-0.0.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pokerkit-plus
+Version: 0.0.1
+Summary: PokerKit Plus — fork-free capability extensions on top of PokerKit; a drop-in superset of pokerkit.
+Project-URL: Homepage, https://github.com/billcheung10/pokerkit-plus
+Project-URL: Repository, https://github.com/billcheung10/pokerkit-plus
+Project-URL: Issues, https://github.com/billcheung10/pokerkit-plus/issues
+Author: PokerKit Plus contributors
+License: MIT
+License-File: LICENSE
+Keywords: equity,holdem,omaha,poker,pokerkit,solver
+Requires-Python: >=3.11
+Requires-Dist: pokerkit==0.7.3
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PokerKit Plus
+
+Fork-free capability extensions on top of [PokerKit](https://github.com/uoftcprg/pokerkit).
+
+`pokerkit_plus` is a **drop-in superset** of `pokerkit`: it re-exports the entire
+upstream surface unchanged and adds new capabilities on top via subclasses, free
+functions, and thin wrappers. The upstream package is never modified, so PokerKit
+Plus keeps riding upstream's maintenance (correctness fixes, new parsers, etc.).
+
+```python
+# Anywhere you used pokerkit, you can use pokerkit_plus instead:
+from pokerkit_plus import NoLimitTexasHoldem, Automation, State   # all of pokerkit
+# ...plus the PokerKit Plus additions as they land.
+```
+
+## Design
+
+- **Form:** standalone extension package, `pip`-depends on `pokerkit==0.7.3` (pinned).
+- **No fork, no monkeypatch.** PokerKit is built for fork-free extension
+  (`_begin_/_update_/_end_` phase hooks, mixin-composed variants, injectable
+  `rake`/`divmod`, `ClassVar` registries). Most additions need zero core edits.
+- **`compat.py`** pins the pokerkit version and is the single home for stable
+  aliases of version-fragile upstream names.
+
+## Status
+
+Semantic layer P0/P1 implemented (drop-in superset of pokerkit + first
+capabilities):
+
+- `pokerkit_plus.texture` — `BoardTexture.from_board` plus `Wetness`,
+  `Connectivity`, `RankBand`, `StraightDraw`, `FlushDraw`, and
+  `are_two_tone`/`are_monotone`/`are_rainbow`.
+- `pokerkit_plus.combos` — `Nuts.from_board`, `CategoryCombos.from_board`,
+  `HoleCombo`, `made_label`, `meets`, `CATEGORY_ORDER` (made-hand category is
+  pokerkit's own `Label`).
+- `pokerkit_plus.draws` — `Draws.from_hand` (hero flush/straight draw + nut
+  rank) and the shared `NutRank`.
+- `pokerkit_plus.tags` — `HandTier.from_hand` (made-hand tier + `labels()`)
+  with `PairTier`/`KickerTier`/`TwoPairTier`/`ThreeOfAKindTier`.
+- `pokerkit_plus.outs` — `Outs.from_hand` (category-upgrade outs, grouped).
+- `pokerkit_plus.blockers` — `BlockerReport.from_hand` (count-based: how many
+  of the board's nut combos a holding removes).
+- `pokerkit_plus.ranges` — `ComboClass`/`expand_range` (notation),
+  `build_value_range`, `calculate_range_advantage` (Monte-Carlo equity), and
+  `nut_advantage` (exact nut-category share).
+- `pokerkit_plus.facade` — `HandReport.from_hand` and `BoardReport.from_board`,
+  the one-call composed entry points for callers wanting a complete reading.
+
+Built on pokerkit's lookup-table total order (no hand-rolled scoring); every
+per-board / per-hand enumeration is memoized, and equity is delegated to
+pokerkit's Monte-Carlo sampler. Verified: mypy `--strict` clean, ruff clean,
+unit tests + doctests green, `Nuts`/`Outs`/blockers match brute-force oracles,
+and a 2000-hand sweep shows no `is_nut`/`nut_rank` contradictions.
+
+### Candidate capabilities (menu, not yet scheduled)
+
+| Capability | Category | Effort |
+|---|---|---|
+| FastState: snapshot/restore + undo for tree search | performance | L |
+| Exact + deterministic equity engine with sampled-hand callbacks | equity | M |
+| Range engine v2: weights, %-ranges, removal-aware combos | equity | M |
+| Structured action-history & rich State view layer | dev-experience | M |
+| Positions + multi-hand Table/session object | dev-experience | M |
+| Bot/agent framework + baseline agents | AI/bots | M |
+| Missing variants: 5/6-card PLO, Big O, Courchevel, 5-Card Draw, A-5 | variants | M |
+| Mixed-game rotation (HORSE / 8-Game) | variants | M |
+| Variant registry + parse-by-name + uniform create | integration | S |
+| Fast lookup-table hand evaluator (5/6/7-card) | performance | L |
+| Robust async multi-variant hand-history I/O | integration | L |
+| State visualization & serialization (ASCII / SVG / JSON) | visualization | S |
+| compat shim + Decimal/currency value type | dev-experience | S |
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT (same as PokerKit).

pokerkit_plus-0.0.1/README.md

@@ -0,0 +1,83 @@
+# PokerKit Plus
+
+Fork-free capability extensions on top of [PokerKit](https://github.com/uoftcprg/pokerkit).
+
+`pokerkit_plus` is a **drop-in superset** of `pokerkit`: it re-exports the entire
+upstream surface unchanged and adds new capabilities on top via subclasses, free
+functions, and thin wrappers. The upstream package is never modified, so PokerKit
+Plus keeps riding upstream's maintenance (correctness fixes, new parsers, etc.).
+
+```python
+# Anywhere you used pokerkit, you can use pokerkit_plus instead:
+from pokerkit_plus import NoLimitTexasHoldem, Automation, State   # all of pokerkit
+# ...plus the PokerKit Plus additions as they land.
+```
+
+## Design
+
+- **Form:** standalone extension package, `pip`-depends on `pokerkit==0.7.3` (pinned).
+- **No fork, no monkeypatch.** PokerKit is built for fork-free extension
+  (`_begin_/_update_/_end_` phase hooks, mixin-composed variants, injectable
+  `rake`/`divmod`, `ClassVar` registries). Most additions need zero core edits.
+- **`compat.py`** pins the pokerkit version and is the single home for stable
+  aliases of version-fragile upstream names.
+
+## Status
+
+Semantic layer P0/P1 implemented (drop-in superset of pokerkit + first
+capabilities):
+
+- `pokerkit_plus.texture` — `BoardTexture.from_board` plus `Wetness`,
+  `Connectivity`, `RankBand`, `StraightDraw`, `FlushDraw`, and
+  `are_two_tone`/`are_monotone`/`are_rainbow`.
+- `pokerkit_plus.combos` — `Nuts.from_board`, `CategoryCombos.from_board`,
+  `HoleCombo`, `made_label`, `meets`, `CATEGORY_ORDER` (made-hand category is
+  pokerkit's own `Label`).
+- `pokerkit_plus.draws` — `Draws.from_hand` (hero flush/straight draw + nut
+  rank) and the shared `NutRank`.
+- `pokerkit_plus.tags` — `HandTier.from_hand` (made-hand tier + `labels()`)
+  with `PairTier`/`KickerTier`/`TwoPairTier`/`ThreeOfAKindTier`.
+- `pokerkit_plus.outs` — `Outs.from_hand` (category-upgrade outs, grouped).
+- `pokerkit_plus.blockers` — `BlockerReport.from_hand` (count-based: how many
+  of the board's nut combos a holding removes).
+- `pokerkit_plus.ranges` — `ComboClass`/`expand_range` (notation),
+  `build_value_range`, `calculate_range_advantage` (Monte-Carlo equity), and
+  `nut_advantage` (exact nut-category share).
+- `pokerkit_plus.facade` — `HandReport.from_hand` and `BoardReport.from_board`,
+  the one-call composed entry points for callers wanting a complete reading.
+
+Built on pokerkit's lookup-table total order (no hand-rolled scoring); every
+per-board / per-hand enumeration is memoized, and equity is delegated to
+pokerkit's Monte-Carlo sampler. Verified: mypy `--strict` clean, ruff clean,
+unit tests + doctests green, `Nuts`/`Outs`/blockers match brute-force oracles,
+and a 2000-hand sweep shows no `is_nut`/`nut_rank` contradictions.
+
+### Candidate capabilities (menu, not yet scheduled)
+
+| Capability | Category | Effort |
+|---|---|---|
+| FastState: snapshot/restore + undo for tree search | performance | L |
+| Exact + deterministic equity engine with sampled-hand callbacks | equity | M |
+| Range engine v2: weights, %-ranges, removal-aware combos | equity | M |
+| Structured action-history & rich State view layer | dev-experience | M |
+| Positions + multi-hand Table/session object | dev-experience | M |
+| Bot/agent framework + baseline agents | AI/bots | M |
+| Missing variants: 5/6-card PLO, Big O, Courchevel, 5-Card Draw, A-5 | variants | M |
+| Mixed-game rotation (HORSE / 8-Game) | variants | M |
+| Variant registry + parse-by-name + uniform create | integration | S |
+| Fast lookup-table hand evaluator (5/6/7-card) | performance | L |
+| Robust async multi-variant hand-history I/O | integration | L |
+| State visualization & serialization (ASCII / SVG / JSON) | visualization | S |
+| compat shim + Decimal/currency value type | dev-experience | S |
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT (same as PokerKit).

pokerkit_plus-0.0.1/pokerkit_plus/__init__.py

@@ -0,0 +1,131 @@
+"""PokerKit Plus — a fork-free, drop-in superset of :mod:`pokerkit`.
+
+Everything importable from :mod:`pokerkit` is re-exported here unchanged, so
+any ``from pokerkit import X`` can become ``from pokerkit_plus import X`` with
+no other change. PokerKit Plus capabilities are layered on top via subclasses,
+free functions, and thin wrappers — the upstream package is never modified.
+
+As capabilities land, their public names are appended to ``_PLUS_ALL`` (and the
+relevant submodule is imported below) so they show up in ``pokerkit_plus``'s
+star-import surface alongside the upstream names.
+"""
+
+from __future__ import annotations
+
+# Re-export the entire upstream surface. pokerkit ships a complete ``__all__``,
+# so the star import is exact and stable.
+from pokerkit import *  # noqa: F401, F403
+from pokerkit import __all__ as _POKERKIT_ALL
+
+# PokerKit Plus additions. Submodules own their public names (no per-module
+# ``__all__``, matching pokerkit's leaf modules); this aggregator imports and
+# registers them, exactly as pokerkit's own ``__init__`` does.
+from pokerkit_plus.combos import (  # noqa: F401
+    CATEGORY_ORDER,
+    CategoryCombos,
+    HoleCombo,
+    Nuts,
+    made_label,
+    meets,
+)
+from pokerkit_plus.texture import (  # noqa: F401
+    BoardTexture,
+    Connectivity,
+    CONNECTIVITY_ORDER,
+    FlushDraw,
+    FLUSH_DRAW_ORDER,
+    RankBand,
+    RANK_BAND_ORDER,
+    StraightDraw,
+    STRAIGHT_DRAW_ORDER,
+    Wetness,
+    WETNESS_ORDER,
+    are_monotone,
+    are_rainbow,
+    are_two_tone,
+)
+from pokerkit_plus.draws import (  # noqa: F401
+    Draws,
+    NutRank,
+    NUT_RANK_ORDER,
+)
+from pokerkit_plus.tags import (  # noqa: F401
+    HandTier,
+    KickerTier,
+    PairTier,
+    ThreeOfAKindTier,
+    TwoPairTier,
+)
+from pokerkit_plus.outs import Outs  # noqa: F401
+from pokerkit_plus.blockers import BlockerReport  # noqa: F401
+from pokerkit_plus.ranges import (  # noqa: F401
+    Advantage,
+    AdvantageBasis,
+    Aggression,
+    AGGRESSION_ORDER,
+    ComboClass,
+    build_value_range,
+    calculate_range_advantage,
+    expand_range,
+    nut_advantage,
+)
+from pokerkit_plus.facade import (  # noqa: F401
+    BoardReport,
+    HandReport,
+)
+
+__version__ = "0.0.1"
+
+_PLUS_ALL: tuple[str, ...] = (
+    # combos
+    'CATEGORY_ORDER',
+    'CategoryCombos',
+    'HoleCombo',
+    'Nuts',
+    'made_label',
+    'meets',
+    # texture
+    'BoardTexture',
+    'Connectivity',
+    'CONNECTIVITY_ORDER',
+    'FlushDraw',
+    'FLUSH_DRAW_ORDER',
+    'RankBand',
+    'RANK_BAND_ORDER',
+    'StraightDraw',
+    'STRAIGHT_DRAW_ORDER',
+    'Wetness',
+    'WETNESS_ORDER',
+    'are_monotone',
+    'are_rainbow',
+    'are_two_tone',
+    # draws
+    'Draws',
+    'NutRank',
+    'NUT_RANK_ORDER',
+    # tags
+    'HandTier',
+    'KickerTier',
+    'PairTier',
+    'ThreeOfAKindTier',
+    'TwoPairTier',
+    # outs
+    'Outs',
+    # blockers
+    'BlockerReport',
+    # ranges
+    'Advantage',
+    'AdvantageBasis',
+    'Aggression',
+    'AGGRESSION_ORDER',
+    'ComboClass',
+    'build_value_range',
+    'calculate_range_advantage',
+    'expand_range',
+    'nut_advantage',
+    # facade
+    'BoardReport',
+    'HandReport',
+)
+
+__all__ = (*_POKERKIT_ALL, *_PLUS_ALL)

pokerkit_plus-0.0.1/pokerkit_plus/_semantic.py

@@ -0,0 +1,249 @@
+""":mod:`pokerkit_plus._semantic` implements private foundations shared
+by the semantic layer.
+
+Nothing here is part of the public surface; these helpers centralize live
+card enumeration, royal-flush refinement, and the single memoized nut
+enumeration that :mod:`pokerkit_plus.combos` (and later blocker/range
+modules) build on. Everything is expressed in terms of :mod:`pokerkit`
+primitives so that strength and category come from PokerKit's lookup-table
+total order rather than any hand-rolled scoring.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from functools import lru_cache
+from itertools import combinations
+from typing import TYPE_CHECKING
+
+from pokerkit.hands import Hand
+from pokerkit.lookups import Label
+from pokerkit.utilities import Card, CardsLike, Deck, Rank, RankOrder
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__BROADWAY: frozenset[Rank] = frozenset(RankOrder.STANDARD[-5:])
+
+
+def _used(*groups: CardsLike) -> frozenset[Card]:
+    """Return the set of cards used (and hence dead) across the groups.
+
+    Each group is normalized through :meth:`pokerkit.utilities.Card.clean`,
+    so hole cards, board cards, and dead cards can be supplied in any
+    cards-like form (a string, a single card, or an iterable of cards).
+
+    >>> sorted(map(repr, _used('AsKs', 'Qd')))
+    ['As', 'Ks', 'Qd']
+    >>> _used() == frozenset()
+    True
+
+    :param groups: The card groups to union together.
+    :return: The frozen set of all used cards.
+    """
+    used: set[Card] = set()
+
+    for group in groups:
+        used.update(Card.clean(group))
+
+    return frozenset(used)
+
+
+def _live_cards(
+        *groups: CardsLike,
+        deck: Deck = Deck.STANDARD,
+) -> Iterator[Card]:
+    """Yield the live cards: deck cards not used by any group.
+
+    The deck is iterated in its native (deterministic) order, so the live
+    cards are yielded deterministically. This is a generator; callers
+    materialize it with ``tuple(...)`` only when they need a collection.
+
+    >>> live = tuple(_live_cards('AsKsQs'))
+    >>> len(live)
+    49
+
+    :param groups: The card groups whose cards are dead.
+    :param deck: The deck of candidate cards, defaults to
+                 :attr:`pokerkit.utilities.Deck.STANDARD`.
+    :return: The iterator of live cards in deck order.
+    """
+    used = _used(*groups)
+
+    for card in deck:
+        if card not in used:
+            yield card
+
+
+def _is_royal(hand: Hand) -> bool:
+    """Return whether the hand is a royal flush.
+
+    PokerKit reports a royal flush as :attr:`pokerkit.lookups.Label`
+    ``.STRAIGHT_FLUSH``; this refines that by checking the five card ranks
+    are exactly the broadway set (ten through ace). The check is on the
+    rank *set*, not on the top card by index, because the steel wheel
+    (``As2s3s4s5s``) also has the ace as its highest card by
+    :attr:`pokerkit.utilities.RankOrder` ``.STANDARD`` index yet is not a
+    royal flush.
+
+    >>> from pokerkit.hands import StandardHighHand
+    >>> _is_royal(StandardHighHand.from_game('AsKs', 'QsJsTs'))
+    True
+    >>> _is_royal(StandardHighHand.from_game('As2s', '3s4s5s'))
+    False
+    >>> _is_royal(StandardHighHand.from_game('AcAd', 'AhAsKc'))
+    False
+
+    :param hand: The hand to test.
+    :return: ``True`` if the hand is a royal flush, otherwise ``False``.
+    """
+    if hand.entry.label is not Label.STRAIGHT_FLUSH:
+        return False
+
+    return frozenset(card.rank for card in hand.cards) == __BROADWAY
+
+
+@dataclass(frozen=True)
+class HoleCombo:
+    """A two-card hole combination together with its made hand.
+
+    Instances are produced by the nut enumeration core and never
+    constructed by users directly; the embedded :attr:`hand` is the
+    already-evaluated best hand for these hole cards on the enumerated
+    board, so consumers never re-evaluate.
+
+    >>> from pokerkit.hands import StandardHighHand
+    >>> hand = StandardHighHand.from_game('TsJs', 'AsKsQs')
+    >>> combo = HoleCombo(tuple(Card.parse('TsJs')), hand)
+    >>> sorted(map(repr, combo.cards))
+    ['Js', 'Ts']
+    >>> combo.as_frozenset == frozenset(Card.parse('TsJs'))
+    True
+
+    :param cards: The two hole cards, in deck order.
+    :param hand: The evaluated best hand these cards make on the board.
+    """
+
+    cards: tuple[Card, ...]
+    """The two hole cards, in deck order."""
+    hand: Hand
+    """The evaluated best hand these cards make on the board."""
+
+    @property
+    def as_frozenset(self) -> frozenset[Card]:
+        """Return the hole cards as a frozen set.
+
+        This is the exact shape consumed by
+        :func:`pokerkit.analysis.parse_range` output and
+        :func:`pokerkit.analysis.calculate_equities` input, so a combo can
+        round-trip into an equity call.
+
+        >>> from pokerkit.hands import StandardHighHand
+        >>> hand = StandardHighHand.from_game('TsJs', 'AsKsQs')
+        >>> combo = HoleCombo(tuple(Card.parse('TsJs')), hand)
+        >>> combo.as_frozenset == frozenset(Card.parse('JsTs'))
+        True
+
+        :return: The hole cards as a frozen set.
+        """
+        return frozenset(self.cards)
+
+
+@dataclass(frozen=True)
+class _NutsCore:
+    """The shared, immutable result of one nut enumeration over a board.
+
+    This is the value cached by :func:`_nuts_core`. A single enumeration
+    pass produces both the nut hand (and the combos tying it) and the
+    per-category grouping of every live combo, so consumers never
+    re-evaluate.
+
+    :param hand: The strongest hand makeable on the board, or ``None`` if
+                 the board is too short to enumerate.
+    :param combos: Every two-card combo whose best hand ties the strongest
+                   hand, each carrying its already-evaluated hand.
+    :param candidate_count: The number of live two-card combos enumerated.
+    :param by_category: Every live combo grouped by its made-hand label, in
+                        enumeration order.
+    """
+
+    hand: Hand | None
+    """The strongest hand makeable on the board, or ``None``."""
+    combos: tuple[HoleCombo, ...]
+    """The combos tying the strongest hand, with evaluated hands."""
+    candidate_count: int
+    """The number of live two-card combos enumerated."""
+    by_category: Mapping[Label, tuple[HoleCombo, ...]]
+    """Every live combo grouped by its made-hand label."""
+
+
+@lru_cache(maxsize=None)
+def _nuts_core(
+        board: frozenset[Card],
+        hand_type: type[Hand],
+        dead: frozenset[Card],
+) -> _NutsCore:
+    """Enumerate a board once, memoized by board, type, and dead cards.
+
+    This is the single source of nut enumeration shared by
+    :class:`pokerkit_plus.combos.Nuts` and
+    :class:`pokerkit_plus.combos.CategoryCombos`. It enumerates every live
+    two-card combo ONCE, calls ``hand_type.from_game_or_none`` exactly once
+    per combo, and in that same pass tracks the running maximum hand (with
+    every tying combo) and groups every combo by its made-hand label. No
+    combo is ever re-classified, and nothing uses ``list.index`` or rebuilds
+    a set per element.
+
+    The cache is keyed on :class:`frozenset` of
+    :class:`pokerkit.utilities.Card`, which is a correct key because
+    ``Card`` is a frozen, hashable dataclass: two boards with the same card
+    set hash and compare equal regardless of order.
+    ``functools.lru_cache`` is chosen over a hand-rolled module dict because
+    all three arguments are already hashable and immutable, the function is
+    pure, and ``lru_cache`` gives thread-safe memoization plus
+    ``cache_info``/``cache_clear`` introspection for free.
+
+    A board with fewer than three cards returns an honest empty core
+    (``hand is None``, no combos) rather than raising or returning ``None``.
+    A board that is itself the nuts (e.g. a quad board) yields *every* live
+    combo as a tying combo, exposed via :attr:`_NutsCore.combos` and
+    :attr:`_NutsCore.candidate_count` so blockers can detect the
+    "no blocker possible" case.
+
+    :param board: The board cards as a frozen set.
+    :param hand_type: The hand type to evaluate with.
+    :param dead: Additional dead (used) cards as a frozen set.
+    :return: The cached enumeration result.
+    """
+    board_cards = tuple(board)
+
+    if len(board_cards) < 3:
+        return _NutsCore(None, (), 0, {})
+
+    max_hand: Hand | None = None
+    tying: list[HoleCombo] = []
+    grouped: dict[Label, list[HoleCombo]] = {}
+    candidate_count = 0
+
+    for hole in combinations(_live_cards(board, dead), 2):
+        candidate_count += 1
+        hand = hand_type.from_game_or_none(hole, board_cards)
+
+        if hand is None:
+            continue
+
+        combo = HoleCombo(hole, hand)
+        grouped.setdefault(hand.entry.label, []).append(combo)
+
+        if max_hand is None or hand > max_hand:
+            max_hand = hand
+            tying = [combo]
+        elif hand == max_hand:
+            tying.append(combo)
+
+    by_category = {
+        label: tuple(combos) for label, combos in grouped.items()
+    }
+
+    return _NutsCore(max_hand, tuple(tying), candidate_count, by_category)