"The Nut" Poker Tutor

"The Nut" Poker Tutor is an interactive heads-up Texas Hold'em application that combines a custom Java game engine with a multi-agent AI system. Players sit across from an LLM-powered opponent that bluffs, raises, and folds with distinct personality and strategy. Meanwhile, a second AI agent — the Coach — provides real-time analysis: pot odds, hand equity, drawing probabilities, and whether the current hand is "the nut" (the best possible hand). The game engine is pure Java with Spring Boot 3.4, using Spring AI to orchestrate two Vertex AI Gemini 2.0 Flash agents with distinct system prompts. The entire app ships as a single Docker container — a multi-stage build bakes the React frontend into the backend's static resources, so one service handles both the API and the UI on the same origin. Spring Security provides CSRF protection on all state-changing requests, and a three-layer rate limiting system prevents runaway AI costs with graceful degradation.

Learning poker strategy is uniquely challenging because it requires simultaneously understanding probability, game theory, psychology, and bankroll management. Beginners often play by feel rather than math, making costly mistakes they don't even recognize. Traditional poker training tools are either static (articles, videos) or expensive (coaching sessions). Free-play poker apps let you practice but offer no feedback on whether your decisions were mathematically sound. There's no accessible tool that lets you play a real hand while understanding the math behind every decision in real time.

The system separates deterministic math from non-deterministic reasoning through a multi-agent architecture. The Game Engine is pure Java — a state machine managing deck shuffling, card dealing, betting rounds (pre-flop through river), pot calculations, and hand evaluation using a deterministic ranking algorithm. No LLM is involved in game mechanics. The Opponent Agent receives the current game state (its hole cards, community cards, pot size, player actions) and a personality-driven system prompt. It reasons about strategy and bluffing, then returns a structured action (fold, call, raise with amount). The Coach Agent receives the same game state from the player's perspective and combines deterministic calculations (pot odds, equity via Monte Carlo simulation, outs counting) with LLM-generated plain-language coaching advice. If the AI rate limit is reached, the opponent silently degrades to random play and coaching falls back to deterministic math only — the game stays playable. The app deploys as a single Docker container with a scripted deploy pipeline that syncs source, builds remotely, and health-checks the container.