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.
- 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.pymanages the virtual environment, dependencies, and server startup.
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
Option 1: Fork the project for development
- Star the project if you want to bookmark it.
- Fork it into your GitHub account.
- Clone your fork:
git clone https://github.com/your-username/QPDS.git
cd QPDSOption 2: Clone the original repository
git clone https://github.com/APhysickui/QPDS.git
cd QPDSpython3 run.pyThe script:
- Detects or creates
venv/; an invalid old environment is backed up asvenv.broken-<timestamp>. - Installs
requirements.txtonly when runtime dependencies are missing. - 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.
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 defaultThe 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.
- Try the frontend at https://aphysickui.github.io/QPDS/.
- The recommended combination is GitHub Pages for static frontend files and Render for the Flask API.
- Use the top-right ⚙️ API button to enter the HTTPS URL provided by Render; it is saved locally in your browser.
- Full deployment steps and notes are in docs/deployment/github-pages-render.md.
- Start QPDS: run
python3 run.pyand visithttp://localhost:8080. - Choose hole cards: click the two empty slots at the top left, then pick your cards.
- 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.
- Describe the opponent: use the opponent-modeling panel to adjust aggression, tightness, and recent bet sizing; add the latest action or notes when available.
- Get a recommendation: request an analysis to see a suggested action and an explanation of the opponent profile.
- Read the manual: the top-right game-manual button explains rules and strategy.
- 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.
- 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.
Each player receives two hole cards and combines them with five community cards to make the best five-card hand.
- Pre-flop: players receive two cards and can call, raise, or fold.
- Flop: three community cards are dealt, followed by betting.
- Turn: a fourth community card is dealt, followed by betting.
- River: the fifth community card is dealt, followed by the final betting round.
- Showdown: remaining hands are compared; the strongest wins.
| 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♠ |
- 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.
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.
- 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.
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:
- Bowling et al., Heads-up limit hold'em poker is solved, Science, 2015.
- Moravcik et al., DeepStack: Expert-level artificial intelligence in heads-up no-limit poker, Science, 2017.
- Brown & Sandholm, Superhuman AI for heads-up no-limit poker: Libratus beats top professionals, Science, 2018.
- Brown & Sandholm, Superhuman AI for multiplayer poker, Science, 2019.
- Zinkevich et al., Regret Minimization in Games with Incomplete Information, NeurIPS 2007.
- 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.
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, andassumptions.
| 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 |
Run the full suite:
source venv/bin/activate
pytestRun selected checks:
pytest tests/test_hand_evaluator.py # Hand evaluator
pytest -k "factor" # Factor-related tests
pytest -v # Verbose outputCoverage 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.
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.txtThe frontend cannot get recommendations
Check:
- The backend is running.
http://localhost:8080/healthshould return{"status": "healthy", "service": "QPDS API"}. - The browser console for CORS or network errors.
- The top-right ⚙️ API configuration. Use
http://localhost:8080locally 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.
- 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.
- 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.
- 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.
MIT; see LICENSE.
- 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.
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.
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.