---
title: Poker decision engine with a calibrated risk knob
license: mit
tags:
- ml-intern
- poker
- decision-engine
- risk-control
- monte-carlo
---

# poker-risk-engine

A poker decision engine where **risk appetite is a single, calibrated scalar
knob** `r ∈ [0,1]` — the piece our survey found missing from every public poker
agent: levers exist in the literature, but nobody ships an aggression dial with
measured, monotone response curves.


## The knob

`r` simultaneously and monotonically controls: calling threshold
(`pot_odds − 0.20·r`), raise threshold (`0.62 − 0.10·r`), bet threshold
(`0.60 − 0.12·r`), and bet sizing (`0.45 + 0.55·r` of pot). Equity is Monte
Carlo vs uniform opponents (treys).

## Calibration (120 seeded scenarios, eval_knobs.py)

| r | VPIP | PFR | Aggr. rate | Bet/pot |
|---|---|---|---|---|
| 0.0 | 0.36 | 0.00 | 0.15 | 0.91 |
| 0.5 | 0.55 | 0.06 | 0.19 | 1.35 |
| 1.0 | 0.72 | 0.16 | 0.22 | 1.82 |

All four aggression metrics are monotone in r (script-verified). **Honest
caveat:** heuristic mean EV rises monotonically to r=1.0 with no interior peak —
under a fold-equity-only EV model, aggression is never penalized, so the EV
curve reflects the EV model's known weakness, not an uncalibrated knob. An EV
model with value-realization dynamics would likely produce the expected
interior peak; that's the next refinement.

## Misread injection: perception noise costs money

Corrupt card reads (rank or suit swaps) at probability p, re-decide at r=0.5:

| p | Action flip rate | Mean EV loss (chips) |
|---|---|---|
| 0.00 | 0.025 | 2.19 |
| 0.05 | 0.042 | 3.86 |
| 0.10 | 0.075 | 8.75 |
| 0.20 | 0.083 | 13.12 |
| 0.30 | 0.167 | **34.26** |

A 30% misread rate costs ~15× more EV than the clean-read baseline — the
quantitative bridge between the perception stack
([ThreeSixNine/poker-table-perception-eval](https://huggingface.co/datasets/ThreeSixNine/poker-table-perception-eval),
detector in
[ThreeSixNine/yolo11n-poker-table-cards](https://huggingface.co/ThreeSixNine/yolo11n-poker-table-cards))
and decision quality.

## Limitations (v0, by design)

Uniform random opponent model (no reads/ranges); single-street decisions (no
future-street planning, no ICM); heuristic EV used only for policy comparison;
preflop is pure equity MC (no charts). See `LIMITATIONS` in decision_engine.py.

## Usage

```python
from decision_engine import RiskEngine, TableState
eng = RiskEngine(n_sims=1500)
st = TableState(hero=["AS", "KD"], board=["AH", "7S", "2D"], pot=160,
                stack=1000, to_call=40, n_players=3, position="BTN",
                street="flop")
print(eng.decide(st, r=0.7))   # {"action": "raise", "amount": ...}
```

Reproduce: `python eval_knobs.py --n-scenarios 120 --sims 1500`