Railbird Eval Library

Canonical, solver-independent Texas Hold'em card facts for Railbird.

The package answers factual questions about a hand and board. It does not decide whether a hand is strategically value, marginal, draw, or air; those labels depend on ranges, action history, sizing, and policy. Consumers can derive coarse labels through an explicit projection without weakening the canonical facts.

API

const {
  analyzeHand,
  analyzeBoard,
  compareHandToRange,
  toLegacyHandFeatures,
} = require('@coffeemood/railbird-eval-library');

const facts = analyzeHand('Ks9s', ['2d', '6h', '8s', '4s']);

facts.made.subtype;                         // 'king_high'
facts.draws.primaryFlushDraw.label;         // 'second_nut_flush_draw'
facts.draws.primaryFlushDraw.outCount;      // 9
facts.relative.percentile;                  // exact-board percentile over legal combos
facts.relative.isNuts;                      // false

analyzeHand(holeCards, board, options?)

Returns:

• exact made category, subtype, best five, rank key, and actual nut status;
• pair position and kicker rank (overpair, top_pair, second_pair, bottom_pair, and more);
• high-card class (ace_high, king_high, etc.) and overcards;
• nut/second-nut/third-nut/lower flush draws;
• gutshots, open-ended draws, double gutters, combo draws, and exact immediate outs;
• backdoor flush and straight paths;
• board-relative percentile and distance from the nut rank class;
• hole-card contribution and whether the board plays.

Pass { includeRelative: false } when exact-board enumeration is unnecessary.

compareHandToRange(holeCards, board, range, options?)

Compares current made-hand rank against a weighted range with collision removal. Ahead, behind, and tie are always reported separately. This is current-street rank comparison, not equity.

analyzeBoard(board)

Returns pairedness, suit texture, rank/suit counts, board straight windows, and the board's made hand on the river.

toLegacyHandFeatures(facts)

Compatibility adapter for the existing madeTier, pairSubtype, and drawFlags shape. It is deliberately outside the core analysis contract.

Boundaries

This package owns card facts. It does not own:

• solver strategy or action EV;
• equity versus a range;
• clean-out calculation against a range;
• blocker/removal interpretation beyond explicit range comparison;
• strategic story labels or SRE archetypes.

Adoption

The initial golden suite contains the existing SRE examples: AA on 7s9sTh, wheel gutshot 34 on A82, nut and second-nut flush draws, board-owned draws, pair position, open-ended and double-gutter structures, and exact ahead/behind/tie range comparison. New consumers should adopt this package first. Existing NAPI, ground-truth, and X-Ray paths should migrate incrementally through adapters after their outputs are compared against the golden suite.