Full-stack AI poker platform for heads-up No-Limit Texas Hold'em: a FastAPI + Socket.IO poker server, PPO-powered poker bots, a reproducible evaluation suite, Docker runtime, Hugging Face model artifacts, and a Next.js demo frontend.

PokerForge lets a player sit at a live web poker table against Easy, Medium, or Hard bots. Medium and Hard are Stable-Baselines3 PPO policies trained in a custom Gymnasium poker environment, then evaluated in the real PokerTable game engine.

The project intentionally reports honest evaluation numbers. Medium and Hard both beat Easy significantly; Hard currently shows only a marginal, statistically weak edge over Medium. That limitation is documented and traced to the current 3-action abstraction creating a ceiling on behavioral differentiation.

When running locally or through Docker:

Route Purpose http://localhost:3000 Landing page http://localhost:3000/play Live playable poker table http://localhost:3000/eval Evaluation dashboard http://localhost:8000/health Backend health check

Latest report: backend/data/eval/evaluation_report.md

9,000 hands · 3 seeds · 1,000 hands per matchup

Matchup Win Rate bb/100 95% CI p-value Significant medium vs easy 71.2% +12.6 [69.6%, 72.8%] 0.0000 yes hard vs easy 71.3% +26.6 [69.7%, 72.9%] 0.0000 yes hard vs medium 51.1% +106.1 [49.3%, 52.9%] 0.2212 no

Behavioral profile:

Bot Fold % Call % Raise % Aggression VPIP PFR 3-bet % Easy 12.0% 56.5% 15.5% 0.22 70.9% 7.6% 11.6% Medium 0.0% 19.4% 76.9% 0.80 99.9% 80.5% 72.2% Hard 0.0% 6.0% 94.0% 0.94 100.0% 95.4% 93.1%

Published model repo:

Runtime model contract:

Model Local path Hugging Face path Medium PPO backend/data/models/medium/ppo_medium_final.zip models/medium/ppo_medium_final.zip Hard PPO backend/data/models/hard/ppo_hard_final.zip models/hard/ppo_hard_final.zip

Download or verify local artifacts:

Prepare and publish the model bundle:

More detail: docs/huggingface_publish.md

Docker is the easiest reproducible runtime after models are present locally or on Hugging Face.

Then open:

Stop:

Notes:

This repo supports old docker-compose because Kali may not ship the newer docker compose plugin.

Backend Docker uses backend/requirements.docker.txt with CPU-only PyTorch to avoid CUDA downloads.

Model files are mounted from backend/data/models and are not baked into the Docker image.

More detail: docs/docker.md

Terminal 1, backend:

Terminal 2, frontend:

Open:

Run the full evaluation:

Export replay-ready hands and sync frontend assets:

The /eval page reads:

Training is intentionally manual and not part of Docker startup.

Medium:

Hard:

Training scripts are not run automatically by tests, Docker, or the server.

Backend tests:

Frontend build:

Backend health after startup:

Document Purpose backend/README.md Backend setup, models, tests, training, evaluation frontend/README.md Frontend setup, pages, evaluation dashboard docs/docker.md Docker runtime details docs/huggingface_publish.md Hugging Face model publishing specs/game_and_env.yaml Game and environment implementation spec specs/bots.yaml Bot and evaluation spec specs/frontend.yaml Frontend dashboard spec

Current PPO policies use a 3-action abstraction: fold, call/check, raise.

Hard vs Medium is not statistically significant yet.

Full NFSP/CFR-style unexploitable training is planned future work, not part of the current runtime.

Built by Rushi Sagar.

Links: