Skip to content
APhysickuiPublic

About

Interactive, bilingual Texas Hold’em decision assistant with a Flask backend, factor-driven recommendations, and a single-file browser UI.

Resources

Stars

9 stars

Watchers

0 watching

Forks

Repository files navigation

QPDS — Quantitative Poker Decision System

English · 简体中文

Python 3.8+ License: MIT Live Demo

QPDS applies quantitative-investing principles to Texas Hold'em decisions. It organizes hole cards, community cards, pot size, and stacks, then uses a multi-factor model to produce data-driven action suggestions and explanations. The frontend provides a bilingual interactive interface, while the Flask backend separates core algorithms into reusable, testable modules.

Highlights

  • Interactive browser UI: select cards, adjust the pot, stacks, and risk preference, and review a live input summary.
  • Approximate strategy engine: combines equity, pot odds, SPR, draw probabilities, and position to produce action weights, break-even equity, and recommendation stability.
  • Bilingual interface: switch English/Chinese UI text, hints, and errors.
  • Modular architecture: evaluators, factor calculations, and decision logic are separated in backend/core.
  • Opponent modeling: sliders and inputs describe aggression, bluff frequency, and bet sizing, with an updated profile and suggestions in the results.
  • Poker-table UI: graphite, green, and red distinguish states and actions in responsive desktop and mobile layouts.
  • One-command launcher: run.py manages the virtual environment, dependencies, and server startup.

Structure

QPDS/
├── backend/
│   ├── api/                  # Flask entry point and routes
│   └── core/                 # Hand evaluation, equity, factors, and decisions
├── frontend/
│   ├── index.html            # Page structure
│   ├── app.js / workbench.js # Game interaction, review, and practice
│   ├── translations.js       # Bilingual strings
│   ├── package.json          # Vite build and tests
│   └── tests/                # Static frontend contract tests
├── docs/                     # Requirements, design, and notes
├── tests/                    # pytest unit tests
├── run.py                    # Quick-start launcher
└── requirements.txt          # Python dependencies

Quick start

Get the code

Option 1: Fork the project for development

  1. Star the project if you want to bookmark it.
  2. Fork it into your GitHub account.
  3. Clone your fork:
git clone https://github.com/your-username/QPDS.git
cd QPDS

Option 2: Clone the original repository

git clone https://github.com/APhysickui/QPDS.git
cd QPDS

Start the service

Recommended: one-command launcher

python3 run.py

The script:

  1. Detects or creates venv/; an invalid old environment is backed up as venv.broken-<timestamp>.
  2. Installs requirements.txt only when runtime dependencies are missing.
  3. Starts the backend API at http://localhost:8080 by default.

Open http://localhost:8080 in your browser. Keep the launcher terminal open and stop it with Ctrl+C. If the page cannot reach the backend, open ⚙️ API configuration at the top right and enter http://localhost:8080.

Manual setup

python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
python -m pip install -r requirements.txt
python -m backend.api.app         # Start the backend on port 8080 by default

The frontend is also served at http://localhost:8080. If needed, point ⚙️ API configuration to the same URL.

Core runtime dependencies are Flask, flask-cors, and NumPy. The launcher backs up broken environments before rebuilding them rather than deleting them.

Deploy online

First-time walkthrough

  1. Start QPDS: run python3 run.py and visit http://localhost:8080.
  2. Choose hole cards: click the two empty slots at the top left, then pick your cards.
  3. Set the situation: choose pre-flop/flop/turn/river, select community cards where applicable, enter the pot, call amount, and both stacks, then select a position. Start with the button (BTN) if unsure.
  4. Describe the opponent: use the opponent-modeling panel to adjust aggression, tightness, and recent bet sizing; add the latest action or notes when available.
  5. Get a recommendation: request an analysis to see a suggested action and an explanation of the opponent profile.
  6. Read the manual: the top-right game-manual button explains rules and strategy.

Suggested first example

  • Hole cards: AA or AK.
  • Street: pre-flop.
  • Position: button (BTN), the most favorable post-flop position.
  • Pot / call: 100 / 20 for a simple ratio.
  • Stacks: 500 each, a typical 100-big-blind depth.

Understand the output

  • Recommended action: raise, call, fold, or another available action.
  • Action weights: relative weights within the current approximate model.
  • Recommendation stability: a heuristic score describing whether the main suggestion survives small input changes; it is not a statistical confidence level.
  • Estimated EV: an estimate under the current range, fold-rate, and bet-sizing assumptions.
  • Break-even equity: the minimum equity threshold for continuing to invest chips.
  • Key factors: equity, pot odds, and other inputs affecting the decision.
  • Opponent profile: aggression, betting pressure, psychological pressure, and suggested adjustments for interpreting the opponent's strategy.

Texas Hold'em rules

Each player receives two hole cards and combines them with five community cards to make the best five-card hand.

Streets

  1. Pre-flop: players receive two cards and can call, raise, or fold.
  2. Flop: three community cards are dealt, followed by betting.
  3. Turn: a fourth community card is dealt, followed by betting.
  4. River: the fifth community card is dealt, followed by the final betting round.
  5. Showdown: remaining hands are compared; the strongest wins.

Hand rankings, strongest first

Hand Description Example
Royal flush A-K-Q-J-10, all one suit A♠ K♠ Q♠ J♠ 10♠
Straight flush Five consecutive cards, one suit 9♥ 8♥ 7♥ 6♥ 5♥
Four of a kind Four cards of the same rank K♣ K♦ K♥ K♠ 3♦
Full house Three of a kind and a pair Q♠ Q♥ Q♦ 7♣ 7♠
Flush Five cards of one suit A♦ J♦ 9♦ 6♦ 2♦
Straight Five consecutive ranks 10♠ 9♥ 8♦ 7♣ 6♠
Three of a kind Three cards of one rank 8♣ 8♦ 8♥ K♠ 4♦
Two pair Two distinct pairs A♠ A♥ 5♣ 5♦ 9♠
One pair Two cards of one rank J♦ J♠ 10♥ 8♣ 3♦
High card None of the above A♠ K♦ Q♥ 8♣ 5♠

Key concepts

  • Pot odds: the relationship between the call amount and the pot.
  • Implied odds: potential winnings on later streets.
  • Position: where you act relative to the dealer; later positions have more information.
  • Stack-to-pot ratio (SPR): effective stack divided by pot size.
  • Draw: a hand that needs particular cards to improve, such as a flush or straight draw.

Positions

Position determines action order and information advantage.

Early position: acts first and generally needs stronger hands.

  • UTG: first to act pre-flop, with the least information.
  • UTG+1 / UTG+2: follow UTG and still need relatively strong starting hands.

Middle position: MP1 / MP2 / MP3 can loosen somewhat and observe earlier actions.

Late position:

  • LJ / HJ: can observe most earlier actions before deciding.
  • CO: the cutoff, immediately before the button.
  • BTN: the button acts last post-flop and has the strongest positional advantage.

Blinds:

  • SB: the small blind acts first post-flop, with money already invested.
  • BB: the big blind has the final pre-flop response opportunity in the initial action order and should consider pot odds.

For beginners: play tighter in early position and wider in late position. The button can open and steal blinds with a wider range; UTG requires greater care.

Strategy terminology

  • TAG: tight-aggressive; fewer, stronger hands played assertively.
  • LAG: loose-aggressive; a wider range with aggressive betting.
  • Value bet: betting a strong hand to earn value.
  • Bluff: betting a weak hand to make opponents fold.
  • Semi-bluff: betting a draw that may improve or induce a fold.

GTO, solved games, and this project's limits

There is no complete “optimal strategy table” that can be applied directly to every Hold'em game. Research results depend on the game variant:

  • Heads-up limit Hold'em (HULHE): Cepheus essentially weakly solved it in 2015. Its strategy cannot be significantly beaten by a human over a lifetime of play; that does not mean a unique action was enumerated for every state.
  • Heads-up no-limit Hold'em (HUNL): DeepStack and Libratus reached superhuman performance using methods such as continual re-solving, abstraction, and subgame solving. These are strong approximate strategies, not exact Nash solutions of the complete game tree.
  • Six-player no-limit Hold'em: Pluribus reached superhuman performance, but exploitability is harder to define and compute in multiplayer non-zero-sum games. The full game has not been solved.

QPDS currently returns strategy_mode=heuristic_equilibrium_approximation. It combines Monte Carlo equity, multi-factor thresholds, and action-size abstraction into mixed frequencies. It does not run a CFR/subgame solver and does not claim to output GTO. confidence_kind=heuristic_stability describes only suggestion stability. The equity endpoint separately returns Monte Carlo standard error and an approximate 95% interval.

Research references:

Core functionality

Frontend

  • Card picker: selected cards are disabled in the deck and can be removed with a click.
  • Street-aware input: switching streets limits the community-card count automatically.
  • Live parameter summary: immediately displays the pot, call amount, stacks, and risk preference.
  • Localized validation: English/Chinese messages guide users to complete required fields.
  • Opponent modeling: aggression, tightness, and emotion sliders combine with recent bet records to produce a profile.

Backend

  • POST /api/get_recommendation: analyzes a situation and returns an action, amount, estimated value, and explanation.
  • POST /api/get_equity: Monte Carlo equity against supplied cards and opponent ranges, including iterations, standard error, and an approximate 95% interval.
  • GET /health: service health check.
  • Responses include factor details and the opponent profile for the UI or other integrations.
  • Recommendation responses expose action_distribution, break_even_equity, strategy_mode, confidence_kind, and assumptions.

Factors

Factor Meaning Range Use
equity Equity against the opponent range 0–1 Baseline hand evaluation
pot_odds Minimum equity needed to call 0–1 Expected-value calculations
hand_strength Current hand-strength score 0–1 Showdown value
stack_to_pot_ratio Effective stack relative to the pot 0–∞ Stack-management guidance
fold_equity Estimated probability the opponent folds 0–1 Bluff decisions
pot_commitment Degree of commitment to the pot 0–1 Risk assessment
position_factor Positional advantage 0–1 Strategy adjustments
opponent_aggression Opponent aggression index 0–1 Attacking tendencies and continuation bets
opponent_tightness Opponent tightness 0–1 Likely starting-range width
betting_pressure Pressure from the current-street bet 0–1 Responding or folding
board_pressure How much the board helps the opponent range 0–1 Board assessment
range_advantage Relative coverage of both ranges 0–1 Which player benefits from the board
psychological_pressure Combined stack, pacing, and momentum pressure 0–1 Psychological-game assessment
bluff_tendency Estimated bluff frequency 0–1 Calling and folding decisions

Tests

Run the full suite:

source venv/bin/activate
pytest

Run selected checks:

pytest tests/test_hand_evaluator.py  # Hand evaluator
pytest -k "factor"                  # Factor-related tests
pytest -v                          # Verbose output

Coverage includes hand/draw recognition, equity and multi-player ties, cache isolation, factor calculations, strategy output, and API input validation. Frontend contracts cover multi-player parameters, zero-value display, uncertainty information, and dialog semantics; these are not full browser end-to-end tests.

Troubleshooting

Dependency installation fails or an old environment is unusable

Run the launcher again: it backs up the invalid environment before rebuilding. You can also create a fresh environment manually:

python3 -m venv venv-new
venv-new/bin/python -m pip install -r requirements.txt

The frontend cannot get recommendations

Check:

  • The backend is running. http://localhost:8080/health should return {"status": "healthy", "service": "QPDS API"}.
  • The browser console for CORS or network errors.
  • The top-right ⚙️ API configuration. Use http://localhost:8080 locally or the deployed Render HTTPS URL.

The interface looks wrong or translations are missing

Refresh or clear the browser cache and make sure JavaScript is loading.

How should I fill out the opponent model?

Start with intuitive slider values: aggression 0 means extremely passive, while 10 means highly aggressive. If you know the latest bet size, note it together with the pot before the action. Otherwise, leave it empty and the profile will use the sliders. Notes help recall an opponent's habits in later hands.

Roadmap

Completed

  • Bilingual interactive frontend and game-state input.
  • Multi-factor calculations and decision REST API.
  • Hold'em rules and game manual.
  • Opponent modeling with sliders, behavioral profiles, and psychological factors.
  • Responsive mobile input, multi-player equity estimates, and transparent approximation fields.

Planned

  • Hand-history analysis: parse historical hands for playback and review.
  • Advanced opponent modeling: combine multiple hands and fit ranges automatically.
  • Persistence: store hand records and statistics.
  • Backtesting: evaluate strategies and suggest improvements.
  • Frontend modernization: migrate to Vue/React and TypeScript.

Longer-term goals

  • Machine learning: optimize strategies from larger hand-history datasets.
  • Solver benchmarks: build small abstract subgames, compute exploitability with CFR/CFR+, and calibrate the heuristics.
  • Multi-player strategy models: extend equity estimates with position, action order, and separate opponent ranges.

License

MIT; see LICENSE.

Acknowledgements

  • Hand evaluation is based on Cactus Kev's evaluator.
  • Monte Carlo simulation draws on PokerStove's design.
  • The quantitative framework draws on modern portfolio theory.

Contact

Open a GitHub issue with questions or suggestions, or visit my blog: https://akuiro24.xyz/.

Disclaimer: this tool is for education and learning only. Check a platform's policies before using poker-assistance software.

Review and practice

Import DPoker hand-history JSON in the review/practice workspace, select one of your decision points, and inspect the hole cards, community cards, pot, and legal betting limits at that moment. Unrevealed opponent cards and later community cards are excluded from the calculation. Situations involving side pots currently provide equity analysis only.

The workspace includes a 13×13 range editor, up to 20 locally saved situations, and practice examples for pre-flop, combination draws, and four-of-a-kind boards. Results include an EV comparison by amount; the recommended action, weights, and sizing use the same candidate results.

Frontend code is split into JS/CSS modules. Open it through http://localhost:8080 or Vite rather than directly with file://. See docs/review-and-replay.md for input definitions, model limits, and record formats.

About

Interactive, bilingual Texas Hold’em decision assistant with a Flask backend, factor-driven recommendations, and a single-file browser UI.

Resources

Stars

9 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages