Initial commit: Hold'em engine, bots, and simulation harness

Kotlin Multiplatform engine (JVM target only for now; androidTarget and
iosArm64 slot in without touching commonMain).

Core:
- HandEvaluator: single-pass 5-7 card evaluation, ~24M evals/sec. Verified
  exhaustively against published frequencies for all 2,598,960 five-card hands.
- Equity: Monte Carlo with ties split. PreflopChart ranks the 169 starting
  hands using all-in equity plus an explicit playability adjustment, so
  looseness means "plays the top N%".
- Table: no-limit betting rounds, side pots, odd-chip splits, uncalled-bet
  refunds, and incomplete (short all-in) raises that correctly do not reopen
  betting.

Bots:
- SkillLevel and PlayStyle are orthogonal axes. Skill drives decision quality
  (rollout accuracy, pot-odds discipline, position awareness, error rate);
  style drives bluffing, sandbagging, aggression, tightness.
- BotMood gives tilt that persists between hands and decays.
- OpponentModel lets Advanced/Expert exploit habitual bettors.
- MathBot emits a DecisionTrace of the numbers behind each decision, which the
  coach will later hand to an LLM to narrate. The LLM never does poker maths.

Simulator:
- 2,200-3,400 hands/sec. Deck RNG is separate from bot RNGs so rollout counts
  cannot shift the deal.
- Controlled skill-ladder test asserts the difficulty gradient is monotonic:
  73.9 / 53.9 / 27.6 / -155.4 bb/100 over 50k hands.

Assets: 52 CC0 English-pattern card faces plus generated backs.

Tests: 30 passing (evaluator, table rules, pre-flop chart).

Known open: win-rate magnitudes ~10x realistic and several profiles looser
than their labels. Tuning, not correctness.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jay
2026-07-25 04:36:03 -04:00
commit 479be1f6b9
82 changed files with 54638 additions and 0 deletions
+101
View File
@@ -0,0 +1,101 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
version="1.1"
width="360"
height="540"
id="svg20298">
<defs
id="defs20300" />
<metadata
id="metadata20303">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
transform="translate(-151.42857,-248.08929)"
id="layer1">
<g
transform="translate(151.42857,-264.27289)"
id="g3088">
<rect
width="359"
height="539"
rx="29.944447"
ry="29.944447"
x="0.5"
y="512.86218"
id="rect6472-8"
style="fill:#ffffff;stroke:#000000;stroke-width:0.99999976" />
<path
d="m 20,542.36208 0,14.99999 0,5 10,0 c 2.77,0 5.00001,2.23 5.00001,5.00005 l 0,14.99996 c 0,2.77001 -2.23001,5.00001 -5.00001,5.00001 -2.77,0 -5,-2.23 -5,-5.00001 l 0,-4.99999 -5,0 0,4.99999 c 0,5.54 4.46,10 10,10 5.54001,0 10,-4.46 10,-10 l 0,-14.99996 c 0,-5.54005 -4.45999,-10.00005 -10,-10.00005 l -5,0 0,-9.99998 5,0 10,0 0,-5.00001 -10,0 -5,0 z"
id="rect3163-6-0-0-2-6"
style="fill:#000000;fill-opacity:1;stroke:none" />
<path
d="m 340,1022.3622 0,-15 0,-5 -10,0 c -2.77,0 -5.00001,-2.23 -5.00001,-5.00006 l 0,-15.00002 c 0,-2.77 2.23001,-5 5.00001,-5 2.77,0 5,2.23 5,5 l 0,5 5,0 0,-5 c 0,-5.54 -4.46,-10 -10,-10 -5.54001,0 -10,4.46 -10,10 l 0,15.00002 c 0,5.54006 4.45999,10.00006 10,10.00006 l 5,0 0,10 -5,0 -10,0 0,5 10,0 5,0 z"
id="rect3163-6-0-0-2-4-7"
style="fill:#000000;fill-opacity:1;stroke:none" />
<g
transform="translate(60,557.36218)"
id="g3008">
<path
d="m 35.007873,55.984252 c 0.992126,4.003937 4.996063,14.031496 11.976378,14.031496 9,0 13.003937,-8.007874 13.003937,-18 C 59.988188,45 57.437006,40.393701 54.992125,35.007874 52.405511,29.267717 48.614172,24.129921 44.999999,18.992126 40.358267,12.401575 30.01181,0 30.01181,0 c 0,0 -10.381889,12.401575 -15.023621,18.992126 C 11.374015,24.129921 7.582677,29.267717 4.9960629,35.007874 2.5866141,40.393701 0,45 0,52.015748 c 0,9.992126 4.0039369,18 13.003937,18 6.980314,0 10.984251,-10.027559 12.01181,-14.031496 0.992126,-0.992126 0.992126,0 0.992126,1.027559 -0.992126,7.972441 -0.992126,9.992126 -2.019685,15.980315 C 22.996062,79.015748 19.984251,90 19.984251,90 c 5.031496,-1.984252 15.023622,-1.984252 20.019685,0 0,0 -3.011811,-10.984252 -4.003937,-17.007874 -0.992126,-5.988189 -0.992126,-8.007874 -1.984252,-15.980315 0,-1.027559 0,-2.019685 0.992126,-1.027559 z"
id="path3010"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" />
</g>
<g
transform="translate(240,557.36218)"
id="g3022">
<path
d="m 35.007873,55.984252 c 0.992126,4.003937 4.996063,14.031496 11.976378,14.031496 9,0 13.003937,-8.007874 13.003937,-18 C 59.988188,45 57.437006,40.393701 54.992125,35.007874 52.405511,29.267717 48.614172,24.129921 44.999999,18.992126 40.358267,12.401575 30.01181,0 30.01181,0 c 0,0 -10.381889,12.401575 -15.023621,18.992126 C 11.374015,24.129921 7.582677,29.267717 4.9960629,35.007874 2.5866141,40.393701 0,45 0,52.015748 c 0,9.992126 4.0039369,18 13.003937,18 6.980314,0 10.984251,-10.027559 12.01181,-14.031496 0.992126,-0.992126 0.992126,0 0.992126,1.027559 -0.992126,7.972441 -0.992126,9.992126 -2.019685,15.980315 C 22.996062,79.015748 19.984251,90 19.984251,90 c 5.031496,-1.984252 15.023622,-1.984252 20.019685,0 0,0 -3.011811,-10.984252 -4.003937,-17.007874 -0.992126,-5.988189 -0.992126,-8.007874 -1.984252,-15.980315 0,-1.027559 0,-2.019685 0.992126,-1.027559 z"
id="path3024"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" />
</g>
<g
transform="translate(150,737.36218)"
id="g3036">
<path
d="m 35.007873,55.984252 c 0.992126,4.003937 4.996063,14.031496 11.976378,14.031496 9,0 13.003937,-8.007874 13.003937,-18 C 59.988188,45 57.437006,40.393701 54.992125,35.007874 52.405511,29.267717 48.614172,24.129921 44.999999,18.992126 40.358267,12.401575 30.01181,0 30.01181,0 c 0,0 -10.381889,12.401575 -15.023621,18.992126 C 11.374015,24.129921 7.582677,29.267717 4.9960629,35.007874 2.5866141,40.393701 0,45 0,52.015748 c 0,9.992126 4.0039369,18 13.003937,18 6.980314,0 10.984251,-10.027559 12.01181,-14.031496 0.992126,-0.992126 0.992126,0 0.992126,1.027559 -0.992126,7.972441 -0.992126,9.992126 -2.019685,15.980315 C 22.996062,79.015748 19.984251,90 19.984251,90 c 5.031496,-1.984252 15.023622,-1.984252 20.019685,0 0,0 -3.011811,-10.984252 -4.003937,-17.007874 -0.992126,-5.988189 -0.992126,-8.007874 -1.984252,-15.980315 0,-1.027559 0,-2.019685 0.992126,-1.027559 z"
id="path3038"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" />
</g>
<g
transform="matrix(1,0,0,-1,60,1007.3622)"
id="g3050">
<path
d="m 35.007873,55.984252 c 0.992126,4.003937 4.996063,14.031496 11.976378,14.031496 9,0 13.003937,-8.007874 13.003937,-18 C 59.988188,45 57.437006,40.393701 54.992125,35.007874 52.405511,29.267717 48.614172,24.129921 44.999999,18.992126 40.358267,12.401575 30.01181,0 30.01181,0 c 0,0 -10.381889,12.401575 -15.023621,18.992126 C 11.374015,24.129921 7.582677,29.267717 4.9960629,35.007874 2.5866141,40.393701 0,45 0,52.015748 c 0,9.992126 4.0039369,18 13.003937,18 6.980314,0 10.984251,-10.027559 12.01181,-14.031496 0.992126,-0.992126 0.992126,0 0.992126,1.027559 -0.992126,7.972441 -0.992126,9.992126 -2.019685,15.980315 C 22.996062,79.015748 19.984251,90 19.984251,90 c 5.031496,-1.984252 15.023622,-1.984252 20.019685,0 0,0 -3.011811,-10.984252 -4.003937,-17.007874 -0.992126,-5.988189 -0.992126,-8.007874 -1.984252,-15.980315 0,-1.027559 0,-2.019685 0.992126,-1.027559 z"
id="path3052"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" />
</g>
<g
transform="matrix(1,0,0,-1,240,1007.3622)"
id="g3064">
<path
d="m 35.007873,55.984252 c 0.992126,4.003937 4.996063,14.031496 11.976378,14.031496 9,0 13.003937,-8.007874 13.003937,-18 C 59.988188,45 57.437006,40.393701 54.992125,35.007874 52.405511,29.267717 48.614172,24.129921 44.999999,18.992126 40.358267,12.401575 30.01181,0 30.01181,0 c 0,0 -10.381889,12.401575 -15.023621,18.992126 C 11.374015,24.129921 7.582677,29.267717 4.9960629,35.007874 2.5866141,40.393701 0,45 0,52.015748 c 0,9.992126 4.0039369,18 13.003937,18 6.980314,0 10.984251,-10.027559 12.01181,-14.031496 0.992126,-0.992126 0.992126,0 0.992126,1.027559 -0.992126,7.972441 -0.992126,9.992126 -2.019685,15.980315 C 22.996062,79.015748 19.984251,90 19.984251,90 c 5.031496,-1.984252 15.023622,-1.984252 20.019685,0 0,0 -3.011811,-10.984252 -4.003937,-17.007874 -0.992126,-5.988189 -0.992126,-8.007874 -1.984252,-15.980315 0,-1.027559 0,-2.019685 0.992126,-1.027559 z"
id="path3066"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none" />
</g>
<path
d="m 32.5,630.36218 c 0.5,2 2.5,7 6,7 4.5,0 6.5,-4 6.5,-9 0,-3.5 -1.289475,-5.80614 -2.5,-8.5 -1.28894,-2.86836 -3.18966,-5.4287 -5,-8 -2.32265,-3.29895 -7.5,-9.5 -7.5,-9.5 0,0 -5.17735,6.20105 -7.5,9.5 -1.81034,2.5713 -3.71106,5.13164 -5,8 -1.210525,2.69386 -2.5,5 -2.5,8.5 0,5 2,9 6.5,9 3.5,0 5.5,-5 6,-7 0.5,-0.5 0.5,0 0.5,0.5 -0.5,4 -0.5,5 -1,8 -0.5,3 -2,8.5 -2,8.5 2.5,-1 7.5,-1 10,0 0,0 -1.5,-5.5 -2,-8.5 -0.5,-3 -0.5,-4 -1,-8 0,-0.5 0,-1 0.5,-0.5 z"
id="path3037-7-4-72"
style="fill:#000000;fill-opacity:1;stroke:none" />
<path
d="m 332.5,934.36218 c 0.5,-2 2.5,-7 6,-7 4.5,0 6.5,4 6.5,9 0,3.5 -1.28947,5.80614 -2.5,8.5 -1.28894,2.86836 -3.18966,5.4287 -5,8 -2.32265,3.29895 -7.5,9.5 -7.5,9.5 0,0 -5.17735,-6.20105 -7.5,-9.5 -1.81034,-2.5713 -3.71106,-5.13164 -5,-8 -1.21053,-2.69386 -2.5,-5 -2.5,-8.5 0,-5 2,-9 6.5,-9 3.5,0 5.5,5 6,7 0.5,0.5 0.5,0 0.5,-0.5 -0.5,-4 -0.5,-5 -1,-8 -0.5,-3 -2,-8.5 -2,-8.5 2.5,1 7.5,1 10,0 0,0 -1.5,5.5 -2,8.5 -0.5,3 -0.5,4 -1,8 0,0.5 0,1 0.5,0.5 z"
id="path3037-7-4-1-2"
style="fill:#000000;fill-opacity:1;stroke:none" />
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 8.4 KiB