PokerKit Development Assistant

Expert assistant for working with PokerKit, a Swift package for poker hand evaluation and equity calculation using lookup table-based algorithms.

Project Context

PokerKit is a Swift package that evaluates poker hands and calculates hand equity against multiple opponents. It uses a lookup table strategy with a large binary data file (HandRanks.dat, ~130MB) for efficient evaluation.

**Minimum Requirements:**

Core Architecture

Protocol-Oriented Design

1. **HandEvaluator Protocol** (`Protocols/HandEvaluator.swift`)

- Main abstraction for hand evaluation strategies

- Methods: `evaluate(card:handle:)` for incremental evaluation, `evaluate(handle:)` for final ranking

2. **LookupTableHandEvaluator** (`Implementation/LookupTableHandEvaluator.swift`)

- Loads 130MB `HandRanks.dat` file from Resources (tracked with Git LFS)

- Supports 5, 6, and 7 card hands

- Uses `HandHandle` for incremental card-by-card evaluation

3. **EquityCalculator Protocol** (`Protocols/EquityCalculator.swift`)

- Interface for equity calculation strategies

- Two modes: unknown opponents and known opponent hands

4. **DefaultEquityCalculator** (`Implementation/DefaultEquityCalculator.swift`)

- Combinatorial analysis + Monte Carlo simulation (1M iterations when combinations exceed 1M)

- Handles incomplete boards (0-5 community cards)

- Properly handles chops and multi-way pots

Key Models

Factory Pattern

```swift

PokerKit.lookupTableHandEvaluator()

PokerKit.defaultEquityCalculator(evaluator:)

```

Development Workflow

Building

```bash

swift build -v

```

Testing

Uses Swift Testing framework (not XCTest):

```bash

Run all tests

swift test -v

Run with xUnit output for CI

swift test -v --xunit-output test-results/test.xml --parallel

Run specific test suite

swift test --filter "HandEvaluatorTests"

```

**Testing Patterns:**

**Test Coverage:**

Linting

SwiftLint runs automatically on PRs via GitHub Actions. To run locally:

```bash

swiftlint

```

Disabled rule: `identifier_name`

Implementation Details

Hand Evaluation Algorithm

1. Start with `HandHandle.empty` (value: 53)

2. For each card: `evaluator.evaluate(card:handle:)` looks up next state via `lookupTable[handle.value + card.id]`

3. After 5-7 cards: `evaluator.evaluate(handle:)` returns final `HandRank`

4. HandRank encodes category and rank for comparison

Equity Calculation Algorithm

**Unknown Opponents Mode:**

**Known Opponents Mode:**

**Monte Carlo Simulation:**

Important Notes

Git LFS Requirement

`HandRanks.dat` is tracked with Git LFS. CI/CD workflows must include:

```bash

git lfs checkout

```

Bundle Resources

Resources are copied (not processed) to support `Bundle.module` access at runtime.

Concurrency

Uses Swift 6 StrictConcurrency feature for thread-safe designs.

Guidance for Claude Code

When working with this codebase:

1. **Always run tests** after making changes to core logic

2. **Verify Git LFS** is configured if modifying resource handling

3. **Use Swift Testing syntax** (`#expect`, `@Test`) not XCTest

4. **Follow protocol-oriented patterns** when extending functionality

5. **Consider performance** when modifying equity calculations (watch for combination explosion)

6. **Preserve SwiftLint compliance** (except disabled `identifier_name` rule)

7. **Test edge cases** for hand evaluation (kickers, suits, rare hands)

8. **Document public APIs** with DocC-compatible comments